GridPad Jetpack Compose layout

GridPad is a Jetpack Compose library that allows you to place UI elements in a predefined grid, manage spans in two dimensions, have flexible controls to manage row and column sizes.

Usage

GridPad is inspired by LazyRow/LazyColumn and LazyVerticalGrid/LazyHorizontalGrid APIs, which makes its use intuitive.

Key features and limitations:

Follows slot API concept.
Not lazy. All content will be measured and placed instantly.
GridPad must have limited bounds.
It's possible to specify the exact place on the grid for each element.
A cell can contain more than one item. The draw order will be the same as the place order.
Each item in a cell can have different spans.
Each item can have horizontal and vertical spans simultaneously.
Each row and column can have a specific size: fixed or weight-based.

Install

Add the dependency below to your module's build.gradle file:

dependencies {
    implementation "com.touchlane:gridpad:1.1.0"
}

Define the grid

Specifying the exact grid size is required, but specifying each row and column size is optional. The following code initializes a 3x4 grid with rows and columns weights equal to 1:

GridPad(cells = GridPadCells(rowCount = 3, columnCount = 4)) {
    // content        
}

By default rows and columns have weight size equal to 1, but it's possible specify different size to specific row or column. The library support 2 types of sizes:

GridPadCellSize.Fixed - fixed size in Dp, not change when the bounds of GridPad change.
GridPadCellSize.Weight - a relative, depends on other weights, remaining space after placing fixed sizes, and the GridPad bounds.

To define a specific size for a row or column you need to use GridPadCells.Builder API:

GridPad(
    cells = GridPadCells.Builder(rowCount = 3, columnCount = 4)
        .rowSize(index = 0, size = GridPadCellSize.Weight(2f))
        .columnSize(index = 3, size = GridPadCellSize.Fixed(90.dp))
        .build()
) {
    // content
}

The algorithm for allocating available space between cells:

All fixed (GridPadCellSize.Fixed) values are subtracted from the available space.
The remaining space is allocated between the remaining cells according to their weight value.

Place the items

A cell content should be wrapped in a item element:

GridPad(
    cells = GridPadCells(rowCount = 3, columnCount = 4)
) {
    item {
        // cell content
    }
}

Items in a GridPad can be placed explicitly and implicitly. In the example above items are placed implicitly. Implicit placing placed the item next to the last placed item (including span size). Placement direction and first placement position depend on placementPolicy. By default, the first placing will be at position [0;0] with a horizontal direction from start to end.

GridPad(
    cells = GridPadCells(rowCount = 4, columnCount = 3)
) {
    item {
        // 1-st item, row = 0, column = 0
    }
    item {
        // 2-nd item, row = 0, column = 1
    }
    item {
        // 3-rd item, row = 0, column = 2
    }
    item {
        // 4-th item, row = 1, column = 0
    }
}

⚠️ When the placement reaches the last cell, the following items will be ignored. Placing items outside the grid is not allowed.

To place an item explicitly needs to specify both properties row and column in the item. When defines row and column property it's also possible to place all items in a different order without regard to the actual location.

GridPad(
    cells = GridPadCells(rowCount = 3, columnCount = 4)
) {
    item(row = 1, column = 2) {
        // cell content
    }
    item(row = 0, column = 1) {
        // cell content
    }
}

⚠️ A cell can contain more than one item. The draw order will be the same as the place order. GridPad does not limit the item's size when the child has an explicit size. That means that the item can go outside the cell bounds.

Placement policy

To define the direction of placement items in an implicit method used the placementPolicy property.

GridPad(
    cells = GridPadCells(rowCount = 3, columnCount = 4),
    placementPolicy = GridPadPlacementPolicy(
        mainAxis = GridPadPlacementPolicy.MainAxis.HORIZONTAL,
        horizontalDirection = GridPadPlacementPolicy.HorizontalDirection.START_END,
        verticalDirection = GridPadPlacementPolicy.VerticalDirection.TOP_BOTTOM
    )
) {
    // content
}

The GridPadPlacementPolicy class has three properties that allow controlling different aspects of placement items.

mainAxis sets the axis along which the item will be placed. When the axis is filled to the end, the next item will be placed on the next axis. If mainAxis is HORIZONTAL then items will be placed sequentially one by one by horizontal line. If mainAxis is VERTICAL then items will be placed sequentially one by one by vertical line.
horizontalDirection sets the direction of placement horizontally. When mainAxis is HORIZONTAL this property describes the direction of placement of the next item. When mainAxis is VERTICAL this property describes the direction of moving to the next axis. The START_END means that the direction of placement items or moving main axis will begin from the start layout direction and move to the end layout direction (depending on LTR or RTL). The END_START means the same but in the opposite order.
verticalDirection sets the direction of placement vertically. When mainAxis is VERTICAL this property describes the direction of placement of the next item. When mainAxis is HORIZONTAL this property describes the direction of moving to the next axis. The TOP_BOTTOM means that the direction of placement items or moving main axis will begin from the top and move to the bottom. The BOTTOM_TOP means the same but in the opposite order.

Spans

By default, each item has a span of 1x1. To change it, specify one or both of the rowSpan and columnSpan properties of the item.

GridPad(
    cells = GridPadCells(rowCount = 3, columnCount = 4)
) {
    item(rowSpan = 3, columnSpan = 2) {
        // row = 0, column = 0, rowSpan = 3, columnSpan = 2
    }
    item(rowSpan = 2, columnSpan = 2) {
        // row = 0, column = 2, rowSpan = 2, columnSpan = 1
    }
}

When an item has a span that goes outside the grid, the item is skipped and doesn't draw at all. You can handle skipping cases by diagnostic logger.

GridPad(
    cells = GridPadCells(rowCount = 3, columnCount = 4)
) {
    item(row = 1, column = 3, rowSpan = 1, columnSpan = 3) {
        // will be skipped in a drawing process because the item is placed in the column range [3;5] 
        // but the maximum allowable is 3
    }
}

⚠️ When you have a complex structure it's highly recommended to use an explicit method of placing all items to avoid unpredictable behavior and mistakes during the placement of the items.

Anchor

When rowSpan or columnSpan is more than 1 then the content is placed relative to the implicit parameter - anchor. The anchor is the point in the corner from which the span expands. The value depends on horizontalDirection and verticalDirection values in the placementPolicy property.

Layout Direction

The library handles the parent's layout direction value. That means that placement in RTL direction with horizontalDirection = START_END will have the same behavior as LTR direction with horizontalDirection = END_START.

Diagnostic

The library doesn't throw any exceptions when an item is tried to place outside of the defined grid. Instead, the library just sends a signal through the special class GridPadDiagnosticLogger, skipping this item and moving to the next one. This silent behavior might be not suitable during the development process, so there is a way to have more control - define a custom listener. As a dev solution, you can just redirect the message to the console log or throw an exception to fix it immediately.

GridPadDiagnosticLogger.skippingItemListener = { message -> 
    Log.w("GridPad", message)
}

Performance

GridPad respect Jetpack Compose recommendations and avoid not necessary recompositions. You can always check restartability and skippability by running the following command in the sample project:

./gradlew assembleRelease -P gridpad.enableComposeCompilerReports=true

Results will be placed under the directory: build/compose_metrics

restartable skippable scheme("[androidx.compose.ui.UiComposable]") fun GridPad(
  stable cells: GridPadCells
  stable modifier: Modifier? = @static Companion
  stable content: @[ExtensionFunctionType] Function1<GridPadScope, Unit>
)

Enjoy using this library?

Join 💫Stargazers to support future development.

License

MIT License

Copyright (c) 2022 Touchlane LLC tech@touchlane.com

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

touchlane/gridpad-android