ContextualFlowColumn

Component in Compose Foundation Layout

[ContextualFlowColumn] is a specialized version of the [FlowColumn] layout. It is designed to enable users to make contextual decisions during the construction of [FlowColumn] layouts.

This component is particularly advantageous when dealing with a large collection of items, allowing for efficient management and display. Unlike traditional [FlowColumn] that composes all items regardless of their visibility, ContextualFlowColumn smartly limits composition to only those items that are visible within its constraints, such as [maxLines] or maxWidth. This approach ensures optimal performance and resource utilization by composing fewer items than the total number available, based on the current context and display parameters.

While maintaining the core functionality of the standard [FlowColumn], [ContextualFlowColumn] operates on an index-based system and composes items sequentially, one after another. This approach provides a perfect way to make contextual decisions and can be an easier way to handle problems such as dynamic see more buttons such as (N+ buttons).

Last updated: 2024-10-22 13:47

Installation

dependencies {
   implementation("androidx.compose.foundation:foundation-layout:1.8.0-alpha04")
}

Overloads

@Composable
@ExperimentalLayoutApi
fun ContextualFlowColumn(
    itemCount: Int,
    modifier: Modifier = Modifier,
    verticalArrangement: Arrangement.Vertical = Arrangement.Top,
    horizontalArrangement: Arrangement.Horizontal = Arrangement.Start,
    itemHorizontalAlignment: Alignment.Horizontal = Alignment.Start,
    maxItemsInEachColumn: Int = Int.MAX_VALUE,
    maxLines: Int = Int.MAX_VALUE,
    overflow: ContextualFlowColumnOverflow = ContextualFlowColumnOverflow.Clip,
    content: @Composable ContextualFlowColumnScope.(index: Int) -> Unit,
)

Parameters

name	description
itemCount	The total number of item composable
modifier	The modifier to be applied to the Row.
verticalArrangement	The vertical arrangement of the layout's virtual column.
horizontalArrangement	The horizontal arrangement of the layout's children.
itemHorizontalAlignment	The cross axis/horizontal alignment of an item in the column.
maxItemsInEachColumn	The maximum number of items per column
maxLines	The maximum number of columns
overflow	The straoadtegy to handle overflowing items
content	The indexed-based content of [ContextualFlowColumnScope]

Code Example

ContextualFlowColMaxLineDynamicSeeMore

@OptIn(ExperimentalLayoutApi::class)
@Composable
fun ContextualFlowColMaxLineDynamicSeeMore() {
    val totalCount = 300
    var maxLines by remember { mutableStateOf(2) }

    Text(
        modifier = Modifier.fillMaxWidth(1f).padding(20.dp),
        text =
            "ContextualFlowColumn (based on Subcompose)" +
                " is great for Large Items & +N dynamic labels",
        fontWeight = FontWeight.Bold
    )

    val moreOrCollapseIndicator =
        @Composable { scope: ContextualFlowColumnOverflowScope ->
            val remainingItems = totalCount - scope.shownItemCount
            DynamicSeeMore(isHorizontal = true, remainingItems = remainingItems) {
                if (remainingItems == 0) {
                    maxLines = 2
                } else {
                    maxLines += 2
                }
            }
        }
    ContextualFlowColumn(
        modifier =
            Modifier.fillMaxWidth(1f)
                .horizontalScroll(rememberScrollState())
                .padding(20.dp)
                .height(200.dp)
                .wrapContentHeight(align = Alignment.Top),
        verticalArrangement = Arrangement.spacedBy(10.dp),
        horizontalArrangement = Arrangement.spacedBy(20.dp),
        maxLines = maxLines,
        overflow =
            ContextualFlowColumnOverflow.expandOrCollapseIndicator(
                minColumnsToShowCollapse = 4,
                expandIndicator = moreOrCollapseIndicator,
                collapseIndicator = moreOrCollapseIndicator
            ),
        itemCount = totalCount
    ) { index ->
        Box(
            modifier =
                Modifier.align(Alignment.CenterHorizontally)
                    .height(50.dp)
                    .width(50.dp)
                    .background(Color.Green)
        ) {
            Text(
                text = index.toString(),
                fontSize = 18.sp,
                modifier = Modifier.padding(3.dp).align(Alignment.Center)
            )
        }
    }
}