Circle Charts

[laurentiuonac]

Discussed in #3

^{Originally posted by hdralexandru April 7, 2023}
📢 Place of discussion for the Circle's Chart API

See the current proposal beneath. React with 👍🏻 if you like it or with 👎🏻 if you don't.
If you 👎🏻 the API, please specify why and suggest an alternative.

The API

We are suggesting the following approach

Pie Chart

See PieChart for more info about bar charts.

@Composable
fun PieChart(
    modifier: Modifier = Modifier,
    slices: List<Slice>,
    sliceColors: List<Color>,
    angleOffset: Float = 0f,
    marginBetweenSlices: Dp = 0.dp,
    labelStyle: TextStyle,
    labelPosition: (index: Int, slice: Slice) -> LabelPosition = { _, _ -> LabelPosition.OUTSIDE },
)

modifier: Modifier

The Modifier object from compose, used for customizing the behaviour of this composable.

data: List<Slice>

Slice is the data class used for passing the information to us.

data class Slice(
    val key: String, // the label acts as a key too
    val percentage: Float,
)

sliceColors: List<Color>

The colors used for each slice. This list should have the same size as slices

angleOffset: Float

By default, we use start drawing the first slice from the 12 o'clock, counter-clockwise.
The user may use this to offset the position from which we start drawing.
The value can be negative.

marginBetweenSlices: Dp

Space between 2 slices. 0 by default.

labelStyle: TextStyle

The style applied to the labels.

labelPosition

enum class LabelPosition {
    INSIDE,
    OUTSIDE,
    NONE;
}

The user has a few options regarding the placement of the labels: inside the slice, outside the slice or no label, if the user wants to handle the labels on their own.

Depending on the size of the slice, the label might not fit inside. This is the reason for why we use a provider function here.

DonutChart

See What is a donut chart for more info about donut chart.

@Composable
fun DonutChart(
    modifier: Modifier = Modifier,
    slices: List<Slice>,
    sliceColors: List<Color>,
    angleOffset: Float,
    donutHoleRatio: Float, /* between 0 and 1 */
    marginBetweenSlices: Dp,
    cornerRadius: CornerSize,
    labelStyle: TextStyle,
    labelPosition: (index: Int, slice: Slice) -> LabelPosition = { _, _ -> LabelPosition.OUTSIDE },
)

Most of the API is the same as in the PieChart section. However, there are a couple of differences.

donutHoleRatio: Float

What percentage of the radius the hole will take. So for donutHoleRatio=0.5f, the hole will be half the size of the canvas.
We need to define min and max values for this. For donutHoleRatio=0f this chart will become a PieChart. For donutHoleRatio=1f, this chart won't be visible at all.

cornerRadius: CornerSize

See CornerSize.