DEV Community: exyte

Jetpack Compose Tutorial: Replicating the Water Level Widget

exyte — Wed, 07 Jun 2023 09:55:24 +0000

Apple's apps and widgets always were a staple of design, and inspirations for our Replicating Series: Activity Application and Card application. When they announced the new Apple Watch Ultra, the design of the depth gauge widget caught our eye, and we thought it would be cool to replicate it on Android! As usual for our Android replicating challenges, we used the Jetpack Compose framework.

This article will tell you how we went about implementing it - creating a wave effect, having the water snap around the text, and blending colors. We feel like this will be useful both to beginners and those already acquainted with Jetpack Compose.

Water Level

First, let's consider the most trivial problem - how to calculate and animate the water level.

enum class WaterLevelState {
    StartReady,
    Animating,
}

Next, we define the duration of the animation and the initial state:

val waveDuration by rememberSaveable { mutableStateOf(waveDurationInMills) }
var waterLevelState by remember { mutableStateOf(WaterLevelState.StartReady) }

After that we need to define how the water's progress should change. It's necessary for recording the progress on the screen as text and for drawing the water level.

val waveProgress by waveProgressAsState(
    timerState = waterLevelState,
    timerDurationInMillis = waveDuration
)

Here's a closer look at waveProgressAsState. We use animatable because it gives us a little more control and customization. For example, we can specify different animationSpec for different states.
Now to calculate the coordinates of the water's edge that needs to be drawn on the screen:

val waterLevel by remember(waveProgress, containerSize.height) {
    derivedStateOf {
        (waveProgress * containerSize.height).toInt()
    }
}

After all this preliminary work we can move on to creating actual waves.

Waves

The most common way to simulate a wave is to use a sine graph that moves horizontally at a certain speed.

We want it to look more realistic, and it will have to flow over the elements on the screen, so we need a more sophisticated approach. The main idea of the implementation is to define a set of points representing the height of the wave. The values are animated to create the wave effect.

First, we create a list with points to store the values:

val points = remember(spacing, containerSize) {
    derivedStateOf {
        (-spacing..containerSize.width + spacing step spacing).map { x ->
            PointF(x.toFloat(), waterLevel)
        }
    }
}

Then, in the case of normal water flow when there are no obstacles in its path, we simply fill it with the values of the water level. We will consider the other cases later.

LevelState.PlainMoving -> {
    points.value.map {
        it.y = waterLevel
    }
}

Consider an animation that will change the height of each point. Animating all the points would take a heavy toll on the performance and battery. So, in order to save resources, we will only use a small number of Float animation values:

@Composable
fun createAnimationsAsState1(
    pointsQuantity: Int,
): MutableList<State<Float>> {
    val animations = remember { mutableListOf<State<Float>>() }
    val random = remember { Random(System.currentTimeMillis()) }
    val infiniteAnimation = rememberInfiniteTransition()

    repeat(pointsQuantity / 2) {
        val durationMillis = random.nextInt(2000, 6000)
        animations += infiniteAnimation.animateFloat(
            initialValue = 0f,
            targetValue = 1f,
            animationSpec = infiniteRepeatable(
                animation = tween(durationMillis),
                repeatMode = RepeatMode.Reverse,
            )
        )
    }
    return animations
}

To prevent the animation from repeating every 15 points and the waves from being identical, we can set the initialMultipliers:

@Composable
fun createInitialMultipliersAsState(pointsQuantity: Int): MutableList<Float> {
    val random = remember { Random(System.currentTimeMillis()) }
    return remember {
        mutableListOf<Float>().apply {
            repeat(pointsQuantity) { this += random.nextFloat() }
        }
    }
}

Now to add the waves - iterate through all the points and calculate the new heights.

points.forEachIndexed { index, pointF ->
    val newIndex = index % animations.size

    var waveHeight = calculateWaveHeight(
        animations[newIndex].value,
        initialMultipliers[index],
        maxHeight
    )
    pointF.y = pointF.y - waveHeight
}
return points

Adding initialMultipliers to currentSize will reduce the possibility of repeating values. And using linear interpolation will help smoothly change the height:

private fun calculateWaveHeight(
    currentSize: Float,
    initialMultipliers: Float,
    maxHeight: Float
): Float {
    var waveHeightPercent = initialMultipliers + currentSize
    if (waveHeightPercent > 1.0f) {
        val diff = waveHeightPercent - 1.0f
        waveHeightPercent = 1.0f - diff
    }

    return lerpF(maxHeight, 0f, waveHeightPercent)
}

Now the most interesting part - how to make the water flow around UI elements.

Interactive water movement

We start by defining 3 states that water has when its level decreases. The PlainMoving name speaks for itself, WaveIsComing is for the moment when the water comes up to the UX element the water will flow around and you have to show it. FlowsAround is the actual moment of flowing around a UI element.

sealed class LevelState {
    object PlainMoving : LevelState()
    object FlowsAround : LevelState()
    object WaveIsComing: LevelState()
}

We understand that the water level is higher than the item if the water level is less than the item position minus the buffer. This area is shown in red on the below picture.

fun isAboveElement(waterLevel: Int, bufferY: Float, position: Offset) = waterLevel < position.y - bufferY

When the water level is at the level of the element, it is too early to start flowing around yet. This area is shown in grey in the next picture.

fun atElementLevel(
    waterLevel: Int,
    buffer: Float,
    elementParams: ElementParams,
) = (waterLevel >= (elementParams.position.y - buffer)) &&
        (waterLevel < (elementParams.position.y + elementParams.size.height * 0.33))

fun isWaterFalls(
    waterLevel: Int,
    elementParams: ElementParams,
) = waterLevel >= (elementParams.position.y + elementParams.size.height * 0.33) &&
        waterLevel <= (elementParams.position.y + elementParams.size.height)

Another question we have to consider is this - how to calculate the timing of the water flow? The animations of the waterfall and of the wave increase occurs when the water level is in the blue zone. Thus, we need to calculate the time at which the water level passes 2/3 of the element's height.

@Composable
fun rememberDropWaterDuration(
    elementSize: IntSize,
    containerSize: IntSize,
    duration: Long,
): Int {
    return remember(
        elementSize,
        containerSize
    ) { (((duration * elementSize.height * 0.66) / (containerSize.height))).toInt() }
}

Let's take a closer look at the flow around the element. The shape of the water flow is based on a parabola - we chose a simple shape for the sake of the tutorial. We use the points shown in the picture through which the parabola passes. We do not extend the parabola below the current water level (the horizontal dim red line).

is LevelState.FlowsAround -> {
    val point1 = PointF(
        position.x,
        position.y - buffer / 5
    )
    val point2 = point1.copy(x = position.x + elementSize.width)
    val point3 = PointF(
        position.x + elementSize.width / 2,
        position.y - buffer
    )
    val p = Parabola(point1, point2, point3)
    points.value.forEach {
        val pr = p.calculate(it.x)
        if (pr > waterLevel) {
            it.y = waterLevel
        } else {
            it.y = pr
        }
    }
}

Let's look at the waterfall animation: we will use the same parabola, changing its height from the initial position, and the OvershootInterpolator for a softer fall effect.

val parabolaHeightMultiplier = animateFloatAsState(
    targetValue = if (levelState == LevelState.WaveIsComing) 0f else -1f,
    animationSpec = tween(
        durationMillis = dropWaterDuration,
        easing = { OvershootInterpolator(6f).getInterpolation(it) }
    )
)

In this case, we use the height multiplier animation so that eventually the height of the parabola becomes 0.

val point1 by remember(position, elementSize, waterLevel, parabolaHeightMultiplier) {
    mutableStateOf(
        PointF(
            position.x,
            waterLevel + (elementSize.height / 3f + buffer / 5) * parabolaHeightMultiplier.value
        )
    )
}
val point2 by remember(position, elementSize, waterLevel, parabolaHeightMultiplier) {
    mutableStateOf(
        PointF(
            position.x + elementSize.width,
            waterLevel + (elementSize.height / 3f + buffer / 5) * parabolaHeightMultiplier.value
        )
    )
}
val point3 by remember(position, elementSize, parabolaHeightMultiplier, waterLevel) {
    mutableStateOf(
        PointF(
            position.x + elementSize.width / 2,
            waterLevel + (elementSize.height / 3f + buffer) * parabolaHeightMultiplier.value
        )
    )
}
return produceState(
    initialValue = Parabola(point1, point2, point3),
    key1 = point1,
    key2 = point2,
    key3 = point3
) {
    this.value = Parabola(point1, point2, point3)
}

In addition, we need to change the size of the waves in places that overlap the UI element, because at the moment of the water falling motion they increase, and then decrease to their normal size.

val point1 by remember(position, elementSize, waterLevel, parabolaHeightMultiplier) {
    mutableStateOf(
        PointF(
            position.x,
            waterLevel + (elementSize.height / 3f + buffer / 5) * parabolaHeightMultiplier.value
        )
    )
}
val point2 by remember(position, elementSize, waterLevel, parabolaHeightMultiplier) {
    mutableStateOf(
        PointF(
            position.x + elementSize.width,
            waterLevel + (elementSize.height / 3f + buffer / 5) * parabolaHeightMultiplier.value
        )
    )
}
val point3 by remember(position, elementSize, parabolaHeightMultiplier, waterLevel) {
    mutableStateOf(
        PointF(
            position.x + elementSize.width / 2,
            waterLevel + (elementSize.height / 3f + buffer) * parabolaHeightMultiplier.value
        )
    )
}
return produceState(
    initialValue = Parabola(point1, point2, point3),
    key1 = point1,
    key2 = point2,
    key3 = point3
) {
    this.value = Parabola(point1, point2, point3)
}

The wave's height is increased in a radius around the UI element for more realism.

val elementRangeX = (position.x - bufferX)..(position.x + elementSize.width + bufferX)
points.forEach { index, pointF ->
    if (levelState.value is LevelState.WaveIsComing && pointF.x in elementRangeX) {
        waveHeight *= waveMultiplier
    }
}

Now it's time for combining everything we have, and add color blending.

Combining all the elements

There are several ways you can paint on the canvas using a blend mode.
The first method that came to mind is to use a bitmap to draw paths, and to draw the text using Blend modes on a bitmapCanvas. This approach uses an old implementation of the canvas from Android view, so we decided to go natively instead - applying BlendMode for color blending. First, we draw waves on the canvas.

Canvas(
    modifier = Modifier
        .background(Water)
        .fillMaxSize()
) {
    drawWaves(paths)
}

During the implementation we use drawIntoCanvas so that we can use paint.pathEffectCornerPathEffect to smooth out the waves.

fun DrawScope.drawWaves(
    paths: Paths,
) {
    drawIntoCanvas {
        it.drawPath(paths.pathList[1], paint.apply {
            color = Blue
        })
        it.drawPath(paths.pathList[0], paint.apply {
            color = Color.Black
            alpha = 0.9f
        })
    }
}

To see how much space the text takes up, we put the Text element into a Box. Since Text does not support blendMode in the layout, we need to draw text on the Canvas using blendMode, so we use the drawWithContent modifier to only draw the text on the Canvas, but not the text element.
To make blend mode work, a new layer needs to be created. To achieve this, we can use .graphicsLayer(compositingStrategy = CompositingStrategy.Offscreen)*. The rendering of the content will always be rendered into an offscreen buffer first and then drawn to the destination, regardless of any other parameters configured on the graphics layer.

(This is an update to our previous implementation that used a .graphicsLayer(alpha = 0.99f) hack. @romainguy helped us with a cleaner choice in the comments).

Box(
    modifier = modifier
        .graphicsLayer(compositingStrategy = CompositingStrategy.Offscreen)
        .drawWithContent {
            drawTextWithBlendMode(
                mask = paths.pathList[0],
                textStyle = textStyle,
                unitTextStyle = unitTextStyle,
                textOffset = textOffset,
                text = text,
                unitTextOffset = unitTextProgress,
                textMeasurer = textMeasurer,
            )
        }
) {
    Text(
        modifier = content().modifier
            .align(content().align)
            .onGloballyPositioned {
                elementParams.position = it.positionInParent()
                elementParams.size = it.size
            },
        text = "46FT",
        style = content().textStyle
    )
}

First we draw the text, then we draw a wave, which is used as a mask. Here's the official documentation regarding different blend modes available to developers

fun DrawScope.drawTextWithBlendMode(
    mask: Path,
    textMeasurer: TextMeasurer,
    textStyle: TextStyle,
    text: String,
    textOffset: Offset,
    unitTextOffset: Offset,
    unitTextStyle: TextStyle,
) {
    drawText(
        textMeasurer = textMeasurer,
        topLeft = textOffset,
        text = text,
        style = textStyle,
    )
    drawText(
        textMeasurer = textMeasurer,
        topLeft = unitTextOffset,
        text = "FT",
        style = unitTextStyle,
    )

    drawPath(
        path = mask,
        color = Water,
        blendMode = BlendMode.SrcIn
    )
}

Now you can see the whole result:

Conclusion

This turned out to be quite a complex implementation, but that's expected given the source material. We were glad that a lot could be done using the native Compose tooling. You can also tweak the parameters to get a more compelling water effect, but we decided to stop at this proof of concept. As usual, the repo contains the full implementation. If you like this tutorial, you can check how to implement the audio dribble app here or find more interesting stuff in our blog.

Jetpack Compose Tutorial: How to use FlowLayout

exyte — Mon, 01 May 2023 12:36:21 +0000

A short tutorial on how to use FlowLayout in Jetpack Compose

At Exyte, we strive to contribute to the open source engineering community by sharing our knowledge and expertise. We regularly write tutorials and release libraries to help other developers improve their skills and create better software. We expand our knowledge base with up-to-date trends and technologies in software development, such as SwiftUI and Jetpack Compose.

Our latest tutorial is on Android FlowLayout, where we demonstrate how to create a flexible layout for displaying views in a flow-like manner.

If you’ve been keeping up with the latest updates in Jetpack Compose, you might have heard about the new FlowRow and FlowColumn composables recently added to Jetpack Compose 1.4.1. Of course, it has already been published in the Accompanist for a while (a group of libraries designed to supplement Jetpack Compose with features often required by developers but not yet available). But now they are available in the base framework and it would be cool to see what they can be used for.

The most important idea in this layout is that we can lay out items in a container when the size of the items or the container is unknown or dynamic. For example, here we have chips (tags) which we place in random order. “Plant-based food” chip does not fit and carries over to the next line.

FlowRow {
    chipsInRow.forEach {
        Chip(text = it.text, pointColor = it.pointColor)
    }
}

For a FlowColumn, it could look like this:

FlowColumn {
    cardsInColumn.forEach { cardData ->
        Card(cardData)
    }
}

Let's take a look at the API:
horizontalArrangement helps to arrange the elements horizontally in a certain order.
verticalAlignment helps align elements if they are of different heights (although this should not be a common case).
maxItemsInEachRow indicates the maximum number of elements we can place in a row. This is very convenient to use in combination with weight modifiers.

fun FlowRow(
    modifier: Modifier = Modifier,
    horizontalArrangement: Arrangement.Horizontal = Arrangement.Start,
    verticalAlignment: Alignment.Vertical = Alignment.Top,
    maxItemsInEachRow: Int = Int.MAX_VALUE,
    content: @Composable RowScope.() -> Unit
)

For the FlowColumn the parameters work the same way, except rotated vertically.
verticalAlignment offers 3 different options that are self-evident:

horizontalArrangement, on the other hand, has more options with some non-obvious ones:

The distinction between SpaceEvenly and SpaceAround might not be obvious. The main difference is that SpaceEvenly, as the name implies, provides a spacing that is even, including the leading and trailing margins. SpaceAround works the same way, but the margins will take half as much space as the distance between the inner elements. Alternatively, you can use an absolute value to keep the interface constant when selecting the RTL (Right to Left) layout: Arrangement.Absolute

If you want to add distance between elements you can use this construction:
Arrangement.spacedBy(5.dp, Alignment.CenterHorizontally)

maxItemsInEachRow can be used together with weight modifiers to make something like this:

All buttons have the weight set to 1 except the zero button, which has the weight set to 2.

FlowRow(maxItemsInEachRow = 4) {
    buttons.forEach {
        FlowButton(
            modifier = Modifier
                .aspectRatio(1 * it.weight)
                .clip(CircleShape)
                .background(it.color)
                .weight(it.weight),
            text = it.text,
            textColor = it.textColor,
        )
    }
}

As you can see, for straight-forward examples the FlowRow and FlowColumn composables are very easy to use - they are a powerful and flexible layout tool for dynamic or unknown sizes. This makes them especially useful for dynamic and responsive interfaces that adapt to different screen sizes and orientations. We expect the examples above to cover most developers’ needs, but we still want to create a more complex example using these new layouts and animating transitions that could happen during adding, removing or repositioning elements. So keep an eye out for the next article on Flow Layout! Meanwhile you can check out our other articles on android development: Dribbble replicating or Androidview&Jetpack Compose tutorial.