DEV Community: Alex

Parameter Injection for Android ViewModels

Alex — Tue, 23 Aug 2022 07:45:24 +0000

Injecting dependencies into our ViewModel is already a good practice, it keeps the implementation flexible and easy to test.

But what about parameters provided to the screen or Fragment? For example Fragment Args or Compose navigation parameters. Often something like an init method is used to receive the parameters from the View and setup the ViewModel. This adds extra steps to our ViewModel we needs to be aware of. Therefore it would be more favourable to, not only get the dependencies, but also the parameters in the constructor.

Setup

For this example let's keep it simple and focus mainly on the handling of the parameter.

We create an App with two screens.

Screen 1 is just a button. Tapping it gets a random number and navigates to Screen 2, handing the random number over as parameter.

Screen 2 receives the random number, creates a View State and simply displays the result as a text.

The screens are created with Jetpack Compose and the example also uses Composes NavHost to navigate, but the same ViewModel code applies for the use of Activities and Fragments. The only difference are the types allowed to be used as parameter. We can see in the following setup, Compose Navigation only allows us to pass parameters as part of the navigation route String.



val navController = rememberNavController()
NavHost(
    navController = navController,
    startDestination = "home
) {
    composable(route = "home") {
        HomeScreen {
            navController.navigate("details/$it")
        }
    }
    composable(route = "details/{randomNumber}") {
        val viewModel = viewModel<DetailsFlowViewModel>()
        DetailsScreen(viewModel = viewModel)
    }
}

As we can see our second screen has the route details/{randomNumber} declaring the parameter randomNumber.

Handle a saved state

Now to the important question. How can we retrieve the parameter in our ViewModel on the second screen after navigation?

The SavedStateHandle class contains the information we need and it is directly injectable into the constructor of a ViewModel.



class DetailsFlowViewModel(
    savedStateHandle: SavedStateHandle
) : ViewModel() {
    ...
}

This is possible with or without the help of a dependency injection framework like Hilt.

SavedStateHandle provides us with two methods to get to our parameter



operator fun <T> get(key: String): T?



fun <T> getStateFlow(key: String, initialValue: T): StateFlow<T>

Depending on what we want to achieve we can use either method. In our case we want to offer a View State flow from our ViewModel to the UI, therefore let's use getStateFlow.



class DetailsFlowViewModel(
    savedStateHandle: SavedStateHandle
) : ViewModel() {
    val state: Flow<DetailsState> = savedStateHandle
        .getStateFlow<String?>("randomNumber", null)
        .map {
            val number = it?.toIntOrNull() ?: throw IllegalArgumentException("You have to provide randomNumber as parameter of type Int when navigating to details")

            // call dependencies as needed
            val result = "Fancy processing: $number"
            DetailsState(result)
        }
}

Important: Since we are using Compose Navigation we first have to retrieve the parameter as a String before we can convert it to its actual type Int. With Fragment Args it would be possible to directly get the parameter as an Int.

One step further

We can already provide our parameter directly to the ViewModels constructor. But there is still a drawback: The ViewModel constructor does not tell us exactly what it wants, but e.g. in tests we need to know to set randomNumber of type String to the SavedStateHandle before passing it to the constructor. Sounds like it requires a lot of knowledge of implementation details.

Wouldn't it be better if the constructor just tells us: I want to have the parameter randomNumber of type Int.

With the help of dependency injection frameworks like Hilt we can achieve this.

To keep it short I'm not going in to details on the basic usage of Hilt in this post. In case you want to read up on Hilt you can go to its Android Developers tutorial

First we create a Qualifier annotation, allowing us to identify our parameter to Hilt.



@Qualifier
@Retention(AnnotationRetention.BINARY)
annotation class RandomNumber

With the Qualifier RandomNumber we can create a small Hilt module, providing our parameter in a ViewModel scope.



@Module
@InstallIn(ViewModelComponent::class)
object DetailsModule {
    @Provides
    @RandomNumber,
    @ViewModelScoped
    fun provideRandomNumber(savedStateHandle: SavedStateHandle): Int =
        savedStateHandle.get<String>("randomNumber")?.toIntOrNull()
            ?: throw IllegalArgumentException("You have to provide randomNumber as parameter with type Int when navigating to details")
}

We install the module in ViewModelComponent making the parameter available for the lifetime of the ViewModel it is injected in. The actual provideRandomNumber method is basically the code we had in the ViewModel earlier, with one difference. We don't use a Flow, but get the value directly.

With the module our ViewModel becomes really simple.



@HiltViewModel
class DetailsHiltViewModel @Inject constructor(
    @RandomNumber randomNumber: Int
) : ViewModel() {
    override val state: Flow<DetailsState> = flow {
        // call dependencies as needed
        val result = "Fancy processing: $randomNumber"
        emit(DetailsState(result))
    }
}

We ask for the parameter we want, using the Qualifier and simply use it to create our View State.

Conclusion

Using parameter injection like shown in this post, does require a little bit more code than injecting a SavedStateHandle or creating an init method, but it separates the different aspects of our app better, allowing for a more readable and testable code.

The whole example with different variants using the SavedStateHandle, Hilt and an Activity can be found on GitHub

In case you are wondering, the same concept can be achieved using Koin as well.

See you in the next one 👋

Parallax Scrolling using LazyColumn

Alex — Mon, 15 Aug 2022 10:35:09 +0000

A parallax scrolling effect is always nice to look at and it catches the attention of the user. Using Jetpack Compose this effect can be implemented fairly easy.

Just another item

In the example we have an image on top of a list with text items. This could mean we have an Image followed by a LazyColumn, but when looking at the API LazyColumn we can not only call the items method and give it a list with data to create our items from.



val list = (0..1_000).map{ "Item $it" }.toList()

LazyColumn {
    items(list) { item ->
        Text(text = item)
    }
}

We can also call multiple item and items methods in the scope of a LazyColumn. It is not limited to just having it call the items function.
For this means, we can use item to display the image, followed by items to create the list.



val list = (0..1_000).map{ "Item $it" }.toList()

LazyColumn {

    item {
        Image(
            painter = resourcePainter(id = R.drawable.image),
            contentDescription = "Top image"),
            contentScale = ContentScale.Crop,
            modifier = Modifier.fillParentMaxWidth()
    }

    items(list) { item ->
        Text(text = item)
    }
}

With that we already have a list with two types of items and of course right now they are scrolling in the same speed.

Not so fast

In order to achieve a parallax effect, we need to reduce the scrolling speed of the image, while keeping the scrolling speed of the other items untouched.

To influence the scrolling we need

A way to get to scrolling information
A way to manipulate the scrolling behaviour of the image.

For the scrolling information we can utilise LazyColumns parameter LazyListState, it contains the information we need. To get to it, instead of keeping the default, we create our own and pass it in.



val lazyListState = rememberLazyListState()

LazyColumn(state = lazyListState){
    ...
}

Derived from the LazyListState we can calculate a slower translation of our image along the y-axis, compared to the other items.



val firstItemTranslationY by remember {
        derivedStateOf {
            when {
                lazyListState.layoutInfo.visibleItemsInfo.isNotEmpty() && lazyListState.firstVisibleItemIndex == 0 -> lazyListState.firstVisibleItemScrollOffset * .6f
                else                                                                                               -> 0f
            }
        }
    }

We check if the image is visible on screen, if not we don't want to do anything and just say behave normally, by returning a translation of 0. As long as the image is visible we take the current scrolling offset and multiple it by a number between 1 and 0. The closer the number is to 1 the slow the image will move with the scrolling. For the parallax scroll effect we want to keep the image longer in the screen as it normally would be.

You can play around with that value to adjust the speed as you like. For this example let's keep it somewhere in the middle with 0.6.

Now we have the value to adjust our images scrolling. But where should be apply it? For that Compose offers a pretty handy Modifier that we can use. Modifier.graphicsLayer provides us with the possibility to manipulate scale, rotation, alpha, translation and more of a Composable it is applied used on.

The translation sounds like a good option. Let's apply Modifier.graphicsLayer to our image and set the vertical translation to the value we just calculated.



...
item {
    Image(
        painter = painterResource(id = R.drawable.image),
        contentDescription = "Top image",
        contentScale = ContentScale.Crop,
        modifier = Modifier
            .fillParentMaxWidth()
            .graphicsLayer {
                translationY = firstItemTranslationY
            }
    )
}
...

Just to play around a little more, let's also fade out the image slowly while it is scrolling.



val visibility by remember {
        derivedStateOf {
            when {
                lazyListState.layoutInfo.visibleItemsInfo.isNotEmpty() && lazyListState.firstVisibleItemIndex == 0 -> {
                    val imageSize = lazyListState.layoutInfo.visibleItemsInfo[0].size
                    val scrollOffset = lazyListState.firstVisibleItemScrollOffset

                    scrollOffset / imageSize.toFloat()
                }
                else                                                                                               -> 1f
            }
        }
    }

The procedure is basically the same as before, the difference is instead of taking the offset of the first item we take its size and its scroll offset and calculate the alpha value.

When we apply it we subtract our calculated visibility from 1 and the image will be fully transparent when it leaves the screen.



.graphicsLayer {
    alpha = 1f - visibility
    translationY = firstItemTranslationY
}

Conclusion

With Jetpack Composes LazyColumn and Modifier.graphicsLayer it is really simple to create a parallax scrolling effect. Calculate the translation derived from the LazyListState and apply it to the Modifier.

The whole code for this can be found on GitHub.

I also added a fading TopBar to this example. I wanted to have the Back Arrow always visible and therefore ended up creating my own TopBar. If you have any ideas on how to make it work with the standard Compose TopBar, leave a comment or write me directly. I would like to hear about it :-).

Hope you enjoyed this small example on parallax scrolling.
See you in the next one 👋.

Make the Labeled Range Slider interactive

Alex — Mon, 08 Aug 2022 06:31:15 +0000

We created a nice looking UI, yet it is pretty useless at the moment. We still have no way to interact with it. Let's fix that.

Our touch handles should be draggable across our bar, position itself instantly when tapping on it and snap to the nearest value when the interaction is done.

Move it

In part 2 of this series we saw how to use gesture detectors. We could use detectTapGestures and detectDragGestures to achieve this. But since we want to do the more or less same thing when tapping or dragging, position the handle to the touch point, we can use the briefly mentioned awaitPointerEventScope to implement a more flexible and better fitting touch handler.

We can define the touch states we are interested in as a sealed class.



sealed class TouchInteraction {
    object NoInteraction : TouchInteraction()
    object Up : TouchInteraction()
    data class Move(val position: Offset) : TouchInteraction()
}

It is enough for us to know if there is currently no interaction, the handle should be moved to a position and that the user lifted their finger.

Our touch handler is then implemented using the pointerInput Modifier.



fun Modifier.touchInteraction(key: Any, block: (TouchInteraction) -> Unit): Modifier =
    pointerInput(key) {
        forEachGesture {
            awaitPointerEventScope {
                do {
                    val event: PointerEvent = awaitPointerEvent()

                    event.changes
                        .forEach { pointerInputChange: PointerInputChange ->
                            if (pointerInputChange.positionChange() != Offset.Zero) pointerInputChange.consume()
                        }

                    block(TouchInteraction.Move(event.changes.first().position))
                } while (event.changes.any { it.pressed })

                block(TouchInteraction.Up)
            }
        }
    }

We await a touch input from the user with awaitPointerEventScope, when we get one we know the user is now interacting with our Labeled Range Slider. We iterate over the events, as long as the users finger stays on our Composable, we get the absolute position of the event and we pass it on as a TouchInteraction.Move event ourselves. As soon as the user lifts their finger, we respond with TouchInteraction.Up giving our UI the chance to react by snapping the handle to the nearest step.

In our Composable we add the Modifier to the canvas, add three state variables to keep track of the current interaction state and add logic to update the position of our handles.



var touchInteractionState by remember { mutableStateOf<TouchInteraction>(TouchInteraction.NoInteraction) }
var moveLeft by remember { mutableStateOf(false) }
var moveRight by remember { mutableStateOf(false) }
...

Canvas(
    modifier = modifier
        .touchInteraction(remember { MutableInteractionSource() }) {
            touchInteractionState = it
        }
) {
    ...
}

when (val touchInteraction = touchInteractionState) {
    is TouchInteraction.Move -> {
        val touchPositionX = touchInteraction.position.x
        if (abs(touchPositionX - leftCirclePosition.x) < abs(touchPositionX - rightCirclePosition.x)) {
            leftCirclePosition = calculateNewLeftCirclePosition(touchPositionX, leftCirclePosition, rightCirclePosition, stepSpacing, stepXCoordinates.first())
            moveLeft = true
        } else {
            rightCirclePosition = calculateNewRightCirclePosition(touchPositionX, leftCirclePosition, rightCirclePosition, stepSpacing, stepXCoordinates.last())
            moveRight = true
        }
    }
    is TouchInteraction.Up   -> {
        moveLeft = false
        moveRight = false
        touchInteractionState = TouchInteraction.NoInteraction
    }
    else                     -> {
        // nothing to do
    }
}

We need to know which handle to move. For that we look at the x position of the touch interaction, calculate the distance between the left and the right handle and move the handle the interaction was closest to. When calculating the new position of the handle we need to take into account, that the handle should not leave the bar and that the two handles should not overlap while moving. To make it clearer let's have a quick look at the calculation of the updated position of the left handle.



private fun calculateNewLeftCirclePosition(
    touchPositionX: Float,
    leftCirclePosition: Offset,
    rightCirclePosition: Offset,
    stepSpacing: Float,
    firstStepXPosition: Float
): Offset = when {
    touchPositionX < firstStepXPosition                    -> leftCirclePosition.copy(x = firstStepXPosition)
    touchPositionX > (rightCirclePosition.x - stepSpacing) -> leftCirclePosition
    else                                                   -> leftCirclePosition.copy(x = touchPositionX)
}

As we can see depending on the touch position, the position of the other handle and the spacing of the steps and in this case the position of the first step, we calculate the new position the left handle is allowed to have.

The handles move while touching the slider, we can tap on a position the handle instantly jumps to it and we even can move between the two handles without lifting the finger.

Make it snappy

The handles don't behave how we want it yet. They should snap to the nearest step after the user lifts their finger, as well as when the controlled handle is changed. To make that happen we update our touch interaction logic, finding the nearest step and its x-coordinate and updating the handle position accordingly.



is TouchInteraction.Move -> {
    val touchPositionX = touchInteraction.position.x
    if (abs(touchPositionX - leftCirclePosition.x) < abs(touchPositionX - rightCirclePosition.x)) {
        leftCirclePosition = calculateNewLeftCirclePosition(touchPositionX, leftCirclePosition, rightCirclePosition, stepSpacing, stepXCoordinates.first())
        moveLeft = true

        if (moveRight) {
            val (closestRightValue, _) = stepXCoordinates.getClosestNumber(rightCirclePosition.x)
            rightCirclePosition = rightCirclePosition.copy(x = closestRightValue)
            moveRight = false
        }
    } else {
        rightCirclePosition = calculateNewRightCirclePosition(touchPositionX, leftCirclePosition, rightCirclePosition, stepSpacing, stepXCoordinates.last())
        moveRight = true

        if (moveLeft) {
            val (closestRightValue, _) = stepXCoordinates.getClosestNumber(leftCirclePosition.x)
            leftCirclePosition = leftCirclePosition.copy(x = closestRightValue)
            moveLeft = false
        }
    }
}
is TouchInteraction.Up   -> {
    val (closestLeftValue, closestLeftIndex) = stepXCoordinates.getClosestNumber(leftCirclePosition.x)
    val (closestRightValue, closestRightIndex) = stepXCoordinates.getClosestNumber(rightCirclePosition.x)
    if (moveLeft) {
        leftCirclePosition = leftCirclePosition.copy(x = closestLeftValue)
        moveLeft = false
    } else if (moveRight) {
        rightCirclePosition = rightCirclePosition.copy(x = closestRightValue)
        moveRight = false
    }
    touchInteractionState = TouchInteraction.NoInteraction
}

Now that already looks like the final result we want to achieve :-). But there is one minor detail missing: We still need to communicate the updated range back to our caller, so they can react on it ;-).

This final step is now pretty easy. We add a callback onRangeChanged as parameter to our Composable.



@Composable
fun <T : Number> LabeledRangeSlider(
    selectedLowerBound: T,
    selectedUpperBound: T,
    steps: List<T>,
    onRangeChanged: (lower: T, upper: T) -> Unit,
    modifier: Modifier = Modifier,
    sliderConfig: SliderConfig = SliderConfig()
)

And simply call it every time the user lifts their finger with the value of the selected steps.



is TouchInteraction.Up   -> {

    val (closestLeftValue, closestLeftIndex) = stepXCoordinates.getClosestNumber(leftCirclePosition.x)

    val (closestRightValue, closestRightIndex) = stepXCoordinates.getClosestNumber(rightCirclePosition.x)

    if (moveLeft) {

        leftCirclePosition = leftCirclePosition.copy(x = closestLeftValue)

        onRangeChanged(steps[closestLeftIndex], steps[closestRightIndex])

        moveLeft = false

    } else if (moveRight) {

        rightCirclePosition = rightCirclePosition.copy(x = closestRightValue)

        onRangeChanged(steps[closestLeftIndex], steps[closestRightIndex])

        moveRight = false

    }

    touchInteractionState = TouchInteraction.NoInteraction

}

Conclusion

We did it 🎉. We created our own Labeled Range Slider from scratch, drawing everything our Composable needs ourselves and making it interactive with the respective Modifier 🥳.

The entire source code of the Labeled Range Slider can be found on GitHub.

I hope you enjoyed following along this series and had some helpful inspiration :-).

Draw the Labeled Range Slider

Alex — Mon, 08 Aug 2022 06:30:00 +0000

In part 4 of this series let's start putting everything we learned so far, and a little more, together and create our Labeled Range Slider.

Draw the UI

To get started we first need to break down the different elements involved in our Composable and how to draw them.

As we can see on the following image we can break down the Labeled Range Slider into 5 elements.

We have

Labels above the slider bar, indicating the values available and selected. The color and font style should reflect our selected range (Red)
A rounded bar in the background, guiding our sliders (Purple)
Step markers, indicating all available values on our bar (Green)
An indication of our selected range on our bar itself (Blue)
And finally our slider handles which we want to drag across the bar to select our range (Orange)

Rounded background bar (Purple)

The simplest element to start with and to setup our Composable is the gray bar in the background guiding our sliders. Before we get to drawing the bar, we first need to do some preparation like calculating the width and height.

For the width we want our bar to fill the entire width of the available space, with some padding for the sliders, but we will come to that later.
To get the size of our Composable we can use Modifier.onSizeChanged and store that value in a state.
Depending on that value we can determine the with of the rect. For the height, we keep it simple and let the caller configure it, but provide a reasonable default of 12 Dp.
Also we add a parameter for the bar color and the size of the rounded corners.

@Composable
fun LabeledRangeSlider(
    modifier: Modifier = Modifier,
    barHeight: Dp = 12.dp,
    barColor: Color = Color.LightGray,
    barCornerRadius: Dp = 6.dp
) {

    var composableSize by remember { mutableStateOf(IntSize(0, 0)) }
    val height = barHeight
    val barWidth = remember(key1 = composableSize) { composableSize.width.toFloat() }
    val barXStart = 0f
    val barYStart = 0f

    Canvas(
        modifier = modifier
            .height(height)
            .onSizeChanged {
                composableSize = it
            }
    ) {
        drawRoundRect(
            color = barColor,
            topLeft = Offset(barXStart, barYStart),
            size = Size(barWidth, barHeight.toPx()),
            cornerRadius = CornerRadius(barCornerRadius.toPx(), barCornerRadius.toPx())
        )
    }
}

We already prepared some variables, like height, barWidth, barXStart and barYStart. We will need them later to calculate a better positioning. The height we put into Modifier.height of our canvas and we use the best practice of allowing to pass a Modifier, so the width can be determined by the caller.

Interesting to note: We made barWidth recalculation dependent on the size of the Composable. Since as long as the size of the Composable does not change we can just remember barWidth.

The result so far looks like this

What we also can see with this small snippet is that we already have the need for some configuration and the need to convert Dp to pixels with toPx for drawing is given.

What we can do to clean this up a little is, like we saw in part 3, introduce a configuration data class.

data class SliderConfig(
    val barHeight: Dp = 12.dp,
    val barColor: Color = Color.LightGray,
    val barCornerRadius: Dp = 6.dp
) {
    context(Density)
    val barHeightPx: Float
        get() = barHeight.toPx()

    context(Density)
    val barCornerRadiusPx
        get() = barCornerRadius.toPx()
}

We moved our config into SliderConfig and with that we can use Context Receivers to encapsulate the conversion to pixels directly in this class. This time we use Density as a Context, because it is implement by DrawScope, but can be used more general. Why? We will see in a bit :-).

Slider handle (Orange)

Next let's add the slider handles. As we can see in the GIF above, the handle has a shadow around it and it also reacts to the touch, by increasing the shadow size.
Without the shadow we could just simply call drawCircle and be done. Unfortunately we can't apply a shadow effect easily with the regular drawCircle function of a canvas. But luckily we can use drawIntoCanvas and its drawCircle function. It allows us to provide a Paint parameter, with which we can implement our shadow.

private fun DrawScope.drawCircleWithShadow(
    position: Offset,
    touched: Boolean,
    sliderConfig: SliderConfig
) {
    val touchAddition = if (touched) {
        sliderConfig.touchCircleShadowTouchedSizeAdditionPx
    } else {
        0f
    }

    drawIntoCanvas {
        val paint = androidx.compose.ui.graphics.Paint()
        val frameworkPaint = paint.asFrameworkPaint()
        frameworkPaint.color = sliderConfig.touchCircleColor.toArgb()
        frameworkPaint.setShadowLayer(
            sliderConfig.touchCircleShadowSizePx + touchAddition,
            0f,
            0f,
            Color.DarkGray.toArgb()
        )
        it.drawCircle(
            position,
            sliderConfig.touchCircleRadiusPx,
            paint
        )
    }
}

As we can see, we create a Paint object and convert it to NativePaint. This gives us access to setShadowLayer. We give the shadow a size, depending on it the circle is touched or not and draw our circle with it.
We also added a little bit more configuration into our SliderConfig class.

With the circle function ready we need to update the calculation of our bar. When the handle is add the end of the bar we don't want it to overlap our Composable or worse go off-screen. Therefore we need to add a little padding to our bar.

For that we now need to access pixel values of our configuration and as we saw above for that we need to be within the Scope of Density object. One way to solve this would be to move the calculation into the onDraw lambda of our canvas. This would mean recalculate these values every time we do a draw, but they only need to be updated if either the Density or the size of our Composable changes.
What we can do is create a small extension function on the size and the Density.

@Composable
private fun <T> Pair<IntSize, Density>.derive(additionalKey: Any? = null, block: Density.() -> T): T =
    remember(key1 = first, key2 = additionalKey) {
        second.block()
    }

And with that we can write our size calculations like this:

val currentDensity = LocalDensity.current
val sizeAndDensity = composableSize to currentDensity

val barYCenter = sizeAndDensity.derive { (height / 2).toPx() }
val barXStart = sizeAndDensity.derive { sliderConfig.touchCircleRadiusPx }
val barYStart = sizeAndDensity.derive { barYCenter - sliderConfig.barHeightPx / 2f }
val barWidth = sizeAndDensity.derive { composableSize.width - 2 * barXStart }

The important piece here is that we always can get the current Density with LocalDensity.current within a Composable.

Let's position our handles at the start and end of the bar for now and draw them.

val leftCirclePosition = remember(key1 = composableSize) {
    Offset(barXStart, barYCenter)
}
val rightCirclePosition = remember(key1 = composableSize) {
    Offset(barXStart + barWidth, barYCenter)
}

...
// in our Canvas
        drawCircleWithShadow(
            leftCirclePosition,
            false,
            sliderConfig
        )

        drawCircleWithShadow(
            rightCirclePosition,
            false,
            sliderConfig
        )

The result up until now looks like this:

Labels and step markers (Red and Green)

Next we want to draw the labels above the bar as well as the step markers. It makes sense to look at them together, because a label and its step marker should be aligned correctly. What we already know is positioning on the y-axis for our labels and the step markers. The labels should be at the top of our Composable and the step markers aligned with the middle of our bar. What we still need is the positioning on the x-axis for the single steps. For that we first of allow to pass steps into our Composable and create a small function to calculate the x coordinates.

private fun calculateStepCoordinatesAndSpacing(
    numberOfSteps: Int,
    barXStart: Float,
    barWidth: Float,
    stepMarkerRadius: Float,
): Pair<FloatArray, Float> {
    val stepOffset = barXStart + stepMarkerRadius
    val stepSpacing = (barWidth - 2 * stepMarkerRadius) / (numberOfSteps - 1)

    val stepXCoordinates = generateSequence(stepOffset) { it + stepSpacing }
        .take(numberOfSteps)
        .toList()

    return stepXCoordinates.toFloatArray() to stepSpacing
}

We calculate the start to be aligned with the start of our bar and depending on the amount of steps we have, we calculate the spacing between them.

Since this calculation is not only dependent on Composable size and Density, but also on the amount of steps, we use our derive function to perform it.

val (stepXCoordinates, stepSpacing) = sizeAndDensity.derive(steps) {
        calculateStepCoordinatesAndSpacing(
            numberOfSteps = steps.size,
            barXStart = barXStart,
            barWidth = barWidth,
            stepMarkerRadius = sliderConfig.stepMarkerRadiusPx
        )
    }

Additionally we provide the steps as a second key to the remember function. This way we can ensure if the steps are changing we can update our Composable.

After we calculated the positions we can draw our labels and step markers.

private fun <T> DrawScope.drawStepMarkersAndLabels(
    steps: List<T>,
    stepXCoordinates: FloatArray,
    leftCirclePosition: Offset,
    rightCirclePosition: Offset,
    barYCenter: Float,
    sliderConfig: SliderConfig
) {
    assert(steps.size == stepXCoordinates.size) { "Step value size and step coordinate size do not match. Value size: ${steps.size}, Coordinate size: ${stepXCoordinates.size}" }

    steps.forEachIndexed { index, step ->
        val stepMarkerCenter = Offset(stepXCoordinates[index], barYCenter)

        val isCurrentlySelectedByLeftCircle =
            (leftCirclePosition.x > (stepMarkerCenter.x - sliderConfig.stepMarkerRadiusPx / 2)) &&
                    (leftCirclePosition.x < (stepMarkerCenter.x + sliderConfig.stepMarkerRadiusPx / 2))
        val isCurrentlySelectedByRightCircle =
            (rightCirclePosition.x > (stepMarkerCenter.x - sliderConfig.stepMarkerRadiusPx / 2)) &&
                    (rightCirclePosition.x < (stepMarkerCenter.x + sliderConfig.stepMarkerRadiusPx / 2))

        val paint = when {
            isCurrentlySelectedByLeftCircle || isCurrentlySelectedByRightCircle                     -> sliderConfig.textSelectedPaint
            stepMarkerCenter.x < leftCirclePosition.x || stepMarkerCenter.x > rightCirclePosition.x -> sliderConfig.textOutOfRangePaint
            else                                                                                    -> sliderConfig.textInRangePaint
        }

        drawCircle(
            color = sliderConfig.stepMarkerColor,
            radius = sliderConfig.stepMarkerRadiusPx,
            alpha = .1f,
            center = stepMarkerCenter
        )

        drawIntoCanvas {
            val stepText = step.toString().let { text ->
                if (text.length > 3) {
                    text.substring(0, 2)
                } else {
                    text
                }
            }
            it.nativeCanvas.drawText(
                stepText,
                stepMarkerCenter.x - (stepText.length * sliderConfig.textSizePx) / 3,
                sliderConfig.textSizePx,
                paint
            )
        }
    }
}

We pass in the calculated x-axis positions and the steps to iterate over them and position the step marker and the label accordingly. As you can see in the drawIntoCanvas function we are accessing the native canvas to draw our label, since the normally canvas does not have a function for drawing text.
Depending on the position of the two handles, we select a different paint, so that labels reflect the selected range in our slider as well.

We added more properties to our SliderConfig to control the colors, the text size, the text offset and the color of the step markers. With the additional sizes we can update the height calculation of our Composable.

val height = remember(key1 = sliderConfig) { sliderConfig.touchCircleRadius * 2 + sliderConfig.textSize.value.dp + sliderConfig.textOffset }

As well as the calculation of our positioning variables.

val barYCenter = sizeAndDensity.derive { composableSize.height - sliderConfig.touchCircleRadiusPx }
val barXStart = sizeAndDensity.derive { sliderConfig.touchCircleRadiusPx - sliderConfig.stepMarkerRadiusPx }
val barYStart = sizeAndDensity.derive { barYCenter - sliderConfig.barHeightPx / 2 }
val barWidth = sizeAndDensity.derive { composableSize.width - 2 * barXStart }
val barCornerRadius = sizeAndDensity.derive { CornerRadius(sliderConfig.barCornerRadiusPx, sliderConfig.barCornerRadiusPx) }

We put the drawStepMarkersAndLabels in our canvas below the drawRoundRect, but above the functions to draw our markers. The result looks like this:

Finalizing the UI (Blue)

As we can see we are almost done with drawing the UI. What's still missing is the indication of the selected range on the bar and to position our handles correctly to the currently selected value.

First we position our handles. For that we want our Composable to be able to receive these values from the caller, since we don't want to manage this kind of state.

@Composable
fun <T : Number> LabeledRangeSlider(
    selectedLowerBound: T,
    selectedUpperBound: T,
    steps: List<T>,
    modifier: Modifier = Modifier,
    sliderConfig: SliderConfig = SliderConfig()
) {
...
}

With these two values we can update the positioning of our handles

var leftCirclePosition by remember(key1 = composableSize) {
    val lowerBoundIdx = steps.indexOf(selectedLowerBound)
    mutableStateOf(Offset(stepXCoordinates[lowerBoundIdx], barYCenter))
}
var rightCirclePosition by remember(key1 = composableSize) {
    val upperBoundIdx = steps.indexOf(selectedUpperBound)
    mutableStateOf(Offset(stepXCoordinates[upperBoundIdx], barYCenter))
}

Now the label of the selected step is correctly drawn with a bold font style.

The last step to complete the drawing of the UI, is to add a drawRect function below drawing the bar background with drawRoundRect.

drawRect(
    color = sliderConfig.barColorInRange,
    topLeft = Offset(leftCirclePosition.x, barYStart),
    size = Size(rightCirclePosition.x - leftCirclePosition.x, sliderConfig.barHeightPx)
)

To see the result better we set our selectedLowerBound and selectedUpperBound to 10 and 90 respectively.

Looks like we finished the drawing part of our Labeled Range Slider :-).

Make it interactive

We are drawing everything we need for our Labeled Range Slider. Now we need to make it interactive. While writing this post I realized it is already pretty long, that's why I decided to split up this part into another post.

Let's jump right into it or visit GitHub to explore the full source code.

Context Receivers

Alex — Tue, 26 Jul 2022 09:55:00 +0000

On this third part we take a look at Kotlin Context Receivers and how it can help us, before we start putting every together in part 4 and finish up our Labeled Range Slider in part 5.

First let's see what a Context Receiver is, before we take a look at how it can help us make our component easier to use.

Important: Kotlin Context Receiver is an experimental API, this means it could still be subject to change in the future, before a final release. Also the IDE support is currently limited as well.

Enabling Context Receivers

Because of the experimental nature of Context Receivers, they are not enabled by default. To enable its usage we need to go to the build.gradle.kts or build.gradle file of our module and add -Xcontext-receivers as a free compiler arg.

In the build.gradle file of an Android module this looks something like this:

android {
    ...
    kotlinOptions {
        jvmTarget = '1.8'
        freeCompilerArgs = ["-Xcontext-receivers"]
    }
}

How it works

With Context Receivers we can add one or more contexts to our functions or methods. This provides the functionality of the declared context within our function, like having another this in that function. We are then able to call methods of that context as if our function is part of the object.

At a first glance this sounds a little bit like extension functions, similar to

fun String.toast(activity: Activity, duration: Int = Toast.LENGTH_LONG) {
    Toast.makeText(activity, this, duration).show()
}

What you can see in this function is, that we also need an Android Activity to call the Toast.makeText function, therefore we need to call the function like this:

"Hello Toast".toast(this@MainActivity)

We know we only want to call this function from an Android Activity, since this shows an UI element. What we can do with Context Receiver, we can declare our toast function to be callable within the Scope of an Android Activity.

context(Activity)
fun String.toast(duration: Int = Toast.LENGTH_LONG) {
    Toast.makeText(this@Activity, this, duration).show()
}

As you can see, we removed the parameter Activity and instead added a Context Receiver, saying this function is valid within the Scope of an Activity. This allows us to call toast without passing an Activity directly, as long as we are within the Scope of one.

"Hello Toast".toast()

On top of that our function now communicates to our team members, that it is only allowed to call this function in an Activity and not e.g. in a background service.

One question that comes up is, what happens when we are not within the Scope of an object needed as Context Receiver?
Just as an example, lets change our toast function to have an Activity and a String as Context Receivers

context(Activity, String)
fun toast(duration: Int = Toast.LENGTH_LONG) {
    Toast.makeText(this@Activity, this@String, duration).show()
}

Now we need our String also to be in Scope. We can achieve this by using Kotlin's with function.

with("Hello Context") {
    toast()
}

Sure, this is a little bit of an odd example, but it demonstrates how we can create a Scope and also how to use multiple Context Receivers :-).

How does this help us?

For our Labeled Range Slider, Context Receivers can help us makes our API cleaner and simpler to use for the caller and for us.

To start simple, we want to draw a text on a canvas and give the user the ability to configure the text size, as well as the horizontal and vertical translation of the positioning. In our Composable we need pixel values to position and draw the text. But we don't want the callers of our Composable to have to calculate pixel values by themselves and offer them an API which can be used with Dp and/or Sp values.
For that we create a configuration class TextConfig, holding the configurable properties and give them some defaults.

class TextConfig(
...
    private val verticalTranslation: Dp = 0.dp,
    private val horizontalTranslation: Dp = 0.dp,
    private val size: TextUnit = 8.sp,
...
)

To be able to convert Dp or Sp values into pixels, we can use toPx, as we already saw in part two of this series. The function toPx is only available while we are within the DrawScope of a canvas. Therefore we could either call toPx manually every time in our canvas or we can use Context Receivers and create a nice computed properties, making it easier to use.

class TextConfig(
...
    private val verticalTranslation: Dp = 0.dp,
    private val horizontalTranslation: Dp = 0.dp,
    private val size: TextUnit = 8.sp,
...
) {
    context(DrawScope)
    val sizePx: Float
        get() = size.toPx()

    context(DrawScope)
    val verticalTranslationPx: Float
        get() = verticalTranslation.toPx()

    context(DrawScope)
    val horizontalTranslationPx: Float
        get() = horizontalTranslation.toPx()
}

With that we can implement our Composable as follows:

@Composable
fun DrawText(
    textConfig: TextConfig
) {

    var enteredText by remember { mutableStateOf("") }

    Column(
        modifier = Modifier.padding(16.dp)
    ) {
        TextField(
            value = enteredText,
            onValueChange = { enteredText = it }
        )
        Canvas(
            modifier = Modifier
                         .fillMaxSize()
                         .background(color = Color.DarkGray)
        ) {
            val paint = Paint().apply {
                textSize = textConfig.sizePx
            }
            val x = (size.width / 2f) - (enteredText.length / 4f * textConfig.sizePx) + textConfig.horizontalTranslationPx
            val y = size.height / 2f + textConfig.sizePx / 2f + textConfig.verticalTranslationPx            

            drawIntoCanvas {    
                it.nativeCanvas.drawText(
                    enteredText,
                    x,
                    y,
                    paint
                )
            }
        }
    }
}

We can see, that as long as we are in the Scope of the Canvas we can call our properties, bounds to the DrawScope, because the lambda of the Canvas provides the DrawScope as an extension function parameter and there as this.

The user of the Composable can provide their configuration with device independent values.

val config = TextConfig(
    size = 32.sp,
    verticalTranslation = 16.dp,
    horizontalTranslation = 32.dp,
)
DrawText(
    textConfig = config
)

Conclusion

With the Context Receivers we can provide a nice API to our users, while also making our lives easier for the implementation of our Composable.

All the code shown here and a little bit more can be found on GitHub.

Now that we know how to draw elements on a canvas, interactive with them using gesture detection and also are able to create a nice simple API, we got all parts ready to implement our Labeled Range Slider.

Go to the fourth part right away

Touch interactions in Jetpack Compose

Alex — Tue, 12 Jul 2022 09:20:00 +0000

After we learned how to draw different shapes on a Canvas in the first part of the series, let’s have a look at how to handle touch interaction in this second part.

Just as a reminder, with this topic we will be able to make our Labeled Range Slider draggable.

To keep it simple we will create a Scribble Composable, to explore how we can handle touch interactions.

Touch Interaction

For a regular interactive Composable we would normally use either the Modifier clickable:



Canvas(
   modifier = Modifier.clickable {
      Log.i("Tag", "Canvas clicked")
   }
) {
   // draw something
}

or the experimental combinedClickable:



Canvas(
   modifier = Modifier.combinedClickable(
      onClick = { Log.i("Tag", "Canvas clicked") },
      onLongClick = { Log.i("Tag", "Canvas long clicked") },
      onDoubleClick = { Log.i("Tag", "Canvas double clicked") }
   )
) {
   // draw something
}

Both work great if we just want to handle a click on the whole Composable.

But for our example, we want to have a little bit more control. We need to know the exact location where the click happens and also if the user drags the finger across the screen or not. Luckily Compose offers us the Modifier pointerInput, which provides the information we need.

Gesture detectors

The easiest way to use pointerInput is to implement one of several already provided gesture detectors.

detectTapGestures: This is most similar to the combinedClickable Modifier, handling tap, double tap, press and long press. The difference this Modifier provides us with the exact position the user taped within our Composable.
detectDragGestures: With this detector we can detect the start, the end and the path a finger is dragged along in our Composable.
detectHorizontalDragGestures: As the name suggests, this is similar to detectDragGestures, but only provides us with the update for horizontal drag movements.
detectVerticalDragGestures: This is like detectHorizontalDragGestures, but only provides vertical drag movements.
detectDragGesturesAfterLongPress: Using this detector we get the same information as detectDragGestures, but only after the user performed a long press.
detectTransformGestures: The transformation gesture detector provides us with updated position information for rotating, panning and zooming gestures.

If these predefined detectors are still not enough and you want full control over how a touch is handled, you can use awaitPointerEventScope.

For our example of a Scribble Composable, we will focus on using detectDragGestures. Since this detector lets us know where the user is starting the touch and also constant updates while the finger is dragged across our Composable.



Canvas(
   modifier = modifier
      .pointerInput(key1 = Unit) {
         detectDragGestures(
            onDragStart = { touch ->
               Log.i("Tag", "Start of the interaction is $touch")
            },
            onDrag = { change, dragAmount ->
               Log.i("Tag", "Dragged $dragAmount; Result $change")
            }
         )
      }
) {
   // draw something
}

Here we registered a drag gesture detector within pointerInput. For the parameter key1 we simply provide Unit. Since we don’t want our detection to be canceled when key1 changes. In pointerInput we then call detectDragGestures. This gives us the information where the user starts the interaction in the callback onDragStart, as well as continuous updates of the path the finger takes in onDrag.

The onDrag callback has two parameters, the second one gives us the delta to the last drag we got. This is not the absolute position of where the finger is right now, but only the change to the last position update. The first parameter on the other hand provides us with more details, like historical data and also the absolute position of the finger on our Composable.

To keep it simple we will be using the first parameter change to get the absolute position for creating a line drawing.



var points by remember { mutableStateOf<List<Offset>>(emptyList()) }

...
         detectDragGestures(
            onDragStart = { touch ->
               points = listOf(touch)
            },
            onDrag = { change, _ ->
               val newPoint = change.position
               points = points + newPoint
            }
         )
...

First we create a mutable state points that can hold a list of Offsets, that will hold the path the finger was dragged along on our Canvas. When the drag gesture begins we create a new list and add the touch point to it. After that we simply can look at change.position, which gives us the absolute position of the touch on our Canvas and we can add this to our path.

This way works and we can get a decent result when drawing our path right now. But if we want to have a smoother result we should consider the historical data as well.



...
onDrag = { change, _ ->
   val pointsFromHistory = change.historical
      .map { it.position }
      .toTypedArray()
   val newPoints = listOf(*pointsFromHistory, change.position)
   points = points + newPoints
}
...

Here we iterate over the historical data, which represents points between two onDrag updates, and get its positions. With that, we simply add the historical positions and the current position to our path list.

All that is now left to do is to draw the path on our Canvas, using the drawPath method we saw in the first part of this series.



...
if (points.size > 1) {
   val path = Path().apply {
      val firstPoint = points.first()
      val rest = points.subList(1, points.size - 1)

      moveTo(firstPoint.x, firstPoint.y)
      rest.forEach {
         lineTo(it.x, it.y)
      }
   }

   drawPath(path, color, style = Stroke(width = lineWidth.toPx()))
}
...

When we have more than one point in our list we create a new Path object, move the start of the Path to our first point and then add all lines we have in our list to the Path. Since we want just lines to be draw without filling the area, we draw our path with the style Stroke.

In this implementation the tightness of the line to be drawn is parametrized as lineWidth of type Dp, but Stoke wants pixels as its width parameter. Luckily the DrawScope of our Canvas offers us with the extension function toPx, with which we can convert Dp to pixels.

Conclusion

We are now able to handle touch interactions on our custom Composable and translate them to actions. With that, we can draw our Labeled Range Slider and also interact with it.

But before we get into implementing it, we take a small excursion to the new Kotlin Context Receivers in part 3.

The whole code of the Scribble Composable can be found on GitHub.

Custom Composable with Jetpack Compose

Alex — Tue, 05 Jul 2022 09:47:00 +0000

Jetpack Compose already offers us a huge library of components to create our UI. But in order to create a more delight and custom experience to the user, we sometimes need to create our own.

In my first article series I want to talk about how to create custom views in Jetpack Compose.

On the example of a Labeled Ranged Slider we go though the steps needed to create a fully custom Composable. I chose this example because the current version of the Range Slider in Compose only offers a Float Range and no easy way to display step aligned labels, changing its appears in accordance to the selected range.

The result of this series will look like this

We will look at three different topics used to create the Composable and in the end we put it all together.

How to draw on a Canvas (This part)
Handling touch interaction
Kotlin Context Receivers (because it’s new and fun :-D)
Draw the Labeled Range Slider
Interact with the Labeled Range slider

All the code and projects will be published on GitHub as we go along.

How to draw on a Canvas

Let’s start with looking at how to draw something on a Canvas within a Composable.

As a first simple step we draw a basic shape, like a circle. To do this we

Create our Composable

Give it a minimum size
Add a Canvas
Draw the circle



@Composable
fun DrawSimpleCircle(
   color: Color,
   modifier: Modifier = Modifier,
   minSize: DpSize = DpSize(32.dp, 32.dp)
) {
   Canvas(modifier = modifier.size(minSize)) {
      drawCircle(color)
   }
}

The result of this Composable will be a circle in the given color, filling the size of the whole Composable, e.g.

Additionally this API allows us to draw our shapes not only with a single color, but also offers a more flexible Brush variant. With a Brush we are able to achieve gradients as well. The example shows a gradient with two colors, but the API allows for a variable list of colors, if desired.



...
drawCircle(
   brush = Brush.radialGradient(
      colors = listOf(
         centerColor, outerColor
      )
   )
)

A Canvas in Compose can of course not only draw circles. It offers a multitude of different drawing methods. Here are examples of the offers methods and a what it might look like.

drawRect

drawRoundRect

drawLine

drawOval

drawArc



...
drawArc(
   color = color,
   startAngle = 180f,  // 0f is at 3 o'clock of the circle
   sweepAngle = 180f,  // go 180° from startAngle
   useCenter = false,  // whether to fill the arc or not
   style = Stroke(width = 2.dp.toPx())
)

drawPath



...
val path = Path().apply {
   lineTo(size.width, 0f)   // line from start to end
   quadraticBezierTo(       // arc from the top to  bottom
      size.width / 2, size.height / 2,
      size.width, size.height
   )
   lineTo(0f, size.height)  // line from end to start
   quadraticBezierTo(       // arc from bottom to top 
      size.width / 2, size.height / 2,
      0f, 0f
   )
   close()                   // link end to start
}

drawPath(
   color = color,
   path = path,
   style = Stroke(width = 2.dp.toPx())
)

drawPoints

drawOutline

drawImage



...

drawImage(

   image = image,

   dstSize = IntSize(size.width.toInt(), size.width.toInt()),

   colorFilter = ColorFilter.lighting(Color.Yellow, Color.Red)

)

Native Canvas

One useful draw function that is not offered directly within the Canvas Composable is the ability to draw a text. But we can still achieve this by using the drawIntoCanvas method. It gives us access to the native Canvas, which offers a drawText method.

Important to note: When using the native Canvas you have to resort to the android.graphics package, using its Paint or Color classes instead of the Compose variants.



Canvas(modifier = modifier.size(minSize)) {

   val paint = android.graphics.Paint()

   paint.textSize = textSize.toPx()

   paint.color = android.graphics.Color.BLACK

   drawIntoCanvas {

      it.nativeCanvas.drawText(text, 0f, 0f, paint)

   }

}

Conclusion

With the Canvas and the native Canvas we are able to draw everything we need for our Labeled Range Slider.

In the next part we will take a look at how we can make our custom Composable interactive, by reacting on touch events. Go directly to part 2.

The code for creating the images in this post can be found on GitHub.