Matriz

Matriz is an Android library providing a Jetpack Compose composable to use a Canvas as a grid. It allows making a rows/columns division of the canvas based on different criterias.

Setup ⚙️

Simply add the dependency:

dependencies {
    TODO()
    implementation("io.github.patxibocos:matriz:$version")
}

Usage 📙

The API is very simple, there is a GridCanvas composable function that wraps a Canvas. This function is parameterized with arguments to calculate the amount of cells of the grid and where will be placed:

GridCanvas(
    sizing = TODO(),
    onDrawCell = { row: Int, column: Int, cellSize: Size ->
        TODO()
    },
    modifier = TODO(),
    contentAlignment = TODO(),
    spacing = TODO(),
)

How does it work ❓

Based on the received sizing and spacing constraints, the total number of columns and rows will be calculated.

For each of the cells contained in the grid the onDrawCell lambda will be called. This lambda receiver is a DrawScope where different drawing functions can be called.

Before calling the lambda, the canvas gets translated to the appropriate coordinates so the drawing scope is relative to the top left corner of the cell. There is no need to take the current row/column nor spacing.

The cellSize argument passed to the lambda will always have the same value. That size can be understood as the bounds which drawing shouldn't surpass. Otherwise two different cells would collision. It is up to clients to respect the cell size when drawing as there is no runtime check (because the original drawing scope is passed without adding any wrapper).

Sizings 📏

There are four different ways to set how the grid of cells will be sized.

Rows

This way the number of rows is fixed, and the amount of resulting columns will depend on the passed aspect ratio that each cell will have:

Sizing.Rows(
    rows = 3,
    cellsAspectRatio = Aspect.CellsRatio(2f),
)

Columns

Similar to Rows sizing but in the opposite way:

Sizing.Columns(
    columns = 3,
    cellsAspectRatio = Aspect.CellsRatio(2f),
)

RowsAndColumns

Here both the number of rows and columns is provided. The third argument allows setting either an aspect ratio for sizing the cells, or filling the entire canvas width and height:

Sizing.RowsAndColumns(
    rows = 3,
    columns = 4,
    aspect = Aspect.Fill,
)

CellSize

This one defines the size (both width and height) of the cells. The number of rows and columns will depend on how many cells fit on the canvas:

Sizing.CellSize(
    size = Size(
        width = 50f,
        height = 30f,
    )
)

Content alignment 📐

It is also possible to set how the cells grid will be placed relative to the canvas. This works the same way as contentAlignment for Box.

In this example, the grid of cells will be centered relative to the canvas:

GridCanvas(
    contentAlignment = Alignment.Center
)

Spacing 🌌

Setting space between cells is also supported via the spacing argument. It can be set both for horizontal and vertical spacing:

GridCanvas(
    spacing = Spacing(
        horizontal = 10f,
        vertical = 20f,
    )
)