Focus Flow 3 — the ring dial on Canvas

A number you have to read

18:42 is accurate. It is also work. Your eye has to find the digits, parse two numbers, and do a small subtraction before you know how you are doing.

A ring tells you the same thing in the time it takes to glance. Three-quarters full means three-quarters left. Nobody reads anything.

That is the whole job of this chapter. The clock stays — you still want the exact figure sometimes — but it moves inside a ring that drains as the phase runs down. And you are going to draw that ring yourself, on a Canvas, out of two arcs and twelve short lines.

No gauge library. None is needed, and by the end of this lesson you will be able to draw any dial you can sketch.

Angles on a screen start at 3 o'clock

Before any code, one fact that trips up everyone the first time.

When you ask Compose to draw an arc, angle zero points to the right — 3 o'clock — and angles grow clockwise. This is inherited from every graphics system going back decades, and it is not going to change to suit you.

1        -90   (12 o'clock)
2              |
3              |
4  180 --------+-------- 0   (3 o'clock)
5              |
6              |
7             90   (6 o'clock)

So twelve o'clock, where a timer obviously ought to start, is -90. That is the entire reason this file opens with a constant called TOP.

The second fact: cos and sin do not speak degrees. They speak radians, where a full turn is about 6.283 rather than 360. One degree is 0.017453292 radians, so multiplying by that number converts. That is the RAD constant.

1// Degrees to radians. cos and sin want radians.
2private const val RAD = 0.017453292f
3
4// 0 degrees points right, so twelve o'clock is -90.
5private const val TOP = -90f
6
7private const val TICKS = 12

Note the f on the end of 0.017453292f and -90f. Without it Kotlin makes a Double, and every drawing command in Compose wants a Float. Getting this wrong is the third entry in the Error Doctor below, and it is a very easy mistake to make.

The shape of the composable

1@Composable
2fun RingDial(
3    fraction: Float,
4    trackColor: Color,
5    progressColor: Color,
6    tickColor: Color,
7    modifier: Modifier = Modifier,
8    thickness: Dp = 18.dp,
9    content: @Composable () -> Unit,
10) {
11    Box(
12        modifier = modifier,
13        contentAlignment = Alignment.Center,
14    ) {
15        Canvas(modifier = Modifier.fillMaxSize()) {
16            // all the drawing happens here
17        }
18        content()
19    }
20}

Four things worth pointing at.

fraction is the only piece of state it takes. Not milliseconds, not a Phase, not a TimerUiState. One Float between 0 and 1. That means RingDial knows nothing about timers and could just as easily show a download, a battery or a score. It is TimerUiState.fraction, the computed property you wrote in chapter 2, that does the converting.

Every colour is a parameter. The dial does not reach for MaterialTheme itself, so the caller decides whether this is a focus ring or a break ring.

content is a slot — a hole the caller fills with whatever they like. Because it is the last parameter, callers can pass it as a trailing lambda, which is why using RingDial looks like using Column.

The Box stacks, the Canvas and the content do not overlap in code. Box draws its children on top of each other in order, centred. So the Canvas goes down first, then content() sits on top of it, in the hole. This layering is deliberate and it is what stops the second-most-common mistake in this lesson: you cannot put a Text inside the Canvas lambda, because that lambda is not composable — it runs later, during drawing.

Drawing the ring

Here is everything inside the Canvas lambda. It is fifty lines and it is the hardest code in the course, so go through it one step at a time.

Why the track and the progress are two separate arcs

You could draw one arc and be done. It would look wrong.

With only the coloured arc, a nearly-finished phase is a lonely sliver floating in space, and your eye has nothing to measure it against. The grey circle underneath is the scale. It says "this is what a full round looks like", so the coloured part means something.

It is the same reason a fuel gauge has a full arc printed on it and a needle on top.

Twelve marks round the rim

The ticks are the only place with real trigonometry, and it is four lines.

The marks are drawn from radius inner all the way out to outer, which is the very edge of the Canvas. That is why line 11 of the first walkthrough subtracts tickLen and gap before working out the ring's radius — the ring has to get out of the way of them.

Putting it on the screen

TimerContent changes shape. The clock and the rounds line stop being siblings of the controls and become the dial's content instead.

1        val scheme = MaterialTheme.colorScheme
2        val focus = state.phase == Phase.FOCUS
3
4        PhasePill(state.phase)
5
6        Spacer(Modifier.height(28.dp))
7
8        RingDial(
9            fraction = state.fraction,
10            trackColor = scheme.surfaceVariant,
11            progressColor =
12                if (focus) scheme.primary
13                else scheme.secondary,
14            tickColor =
15                scheme.outline.copy(alpha = 0.35f),
16            modifier = Modifier.size(280.dp),
17        ) {
18            Column(
19                horizontalAlignment =
20                    Alignment.CenterHorizontally,
21            ) {
22                Text(
23                    text = formatClock(state.leftMs),
24                    style = MaterialTheme.typography
25                        .displayLarge,
26                    color = scheme.onSurface,
27                )
28                Text(
29                    text = roundsLine(state.rounds),
30                    style = MaterialTheme.typography
31                        .bodyMedium,
32                    color = scheme.onSurfaceVariant,
33                )
34            }
35        }
36
37        Spacer(Modifier.height(36.dp))
38
39        Controls(
40            running = state.running,
41            onToggle = onToggle,
42            onReset = onReset,
43        )
44
45        Spacer(Modifier.height(20.dp))
46
47        Text(
48            text = "Up next: " +
49                state.phase.other.label.lowercase(),
50            style = MaterialTheme.typography.bodySmall,
51            color = scheme.onSurfaceVariant,
52        )

Modifier.size(280.dp) is not decoration — it is what gives the Canvas something to fill. The Box inside RingDial takes that size, the Canvas matches the Box, and every radius in the drawing code is worked out from it.

The progress colour switches with the phase: indigo while you focus, teal while you rest. The tick colour is scheme.outline with alpha = 0.35f — the theme's outline colour at 35 percent opacity, so the marks read as a printed rim rather than as twelve more things to look at.

And state.fraction recomputes on every tick of the timer, ten times a second. Each new value is a new TimerUiState, which triggers recomposition, which redraws the Canvas with a slightly smaller sweep. There is no animation code anywhere. The ring moves because the state moves.

Finally, "Up next: break" under the controls. state.phase.other is the Phase enum's computed property from chapter 2 doing its second useful thing.