Skip to content

Commit

Permalink
Document the public API within redwood-lazylayout-compose (#1771)
Browse files Browse the repository at this point in the history
  • Loading branch information
veyndan authored Jan 15, 2024
1 parent b368a9e commit f11c70c
Show file tree
Hide file tree
Showing 2 changed files with 160 additions and 0 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -22,25 +22,51 @@ import app.cash.redwood.layout.api.Constraint
import app.cash.redwood.layout.api.CrossAxisAlignment
import app.cash.redwood.ui.Margin

/**
* Receiver scope which is used by [LazyColumn] and [LazyRow].
*/
@LayoutScopeMarker
public interface LazyListScope {
/**
* Adds a single item.
*
* @param content The content of the item.
*/
public fun item(
content: @Composable () -> Unit,
)

/**
* Adds a [count] of items.
*
* @param count The items count.
* @param itemContent The content displayed by a single item.
*/
public fun items(
count: Int,
itemContent: @Composable (index: Int) -> Unit,
)
}

/**
* Adds a list of items.
*
* @param items The data list.
* @param itemContent The content displayed by a single item.
*/
public inline fun <T> LazyListScope.items(
items: List<T>,
crossinline itemContent: @Composable (item: T) -> Unit,
): Unit = items(items.size) {
itemContent(items[it])
}

/**
* Adds a list of items where the content of an item is aware of its index.
*
* @param items The data list.
* @param itemContent The content displayed by a single item.
*/
public inline fun <T> LazyListScope.itemsIndexed(
items: List<T>,
crossinline itemContent: @Composable (index: Int, item: T) -> Unit,
Expand All @@ -50,6 +76,12 @@ public inline fun <T> LazyListScope.itemsIndexed(
itemContent(it, items[it])
}

/**
* Adds an array of items.
*
* @param items The data array.
* @param itemContent The content displayed by a single item.
*/
public inline fun <T> LazyListScope.items(
items: Array<T>,
crossinline itemContent: @Composable (item: T) -> Unit,
Expand All @@ -59,6 +91,12 @@ public inline fun <T> LazyListScope.items(
itemContent(items[it])
}

/**
* Adds an array of items where the content of an item is aware of its index.
*
* @param items The data array.
* @param itemContent The content displayed by a single item.
*/
public inline fun <T> LazyListScope.itemsIndexed(
items: Array<T>,
crossinline itemContent: @Composable (index: Int, item: T) -> Unit,
Expand All @@ -71,6 +109,31 @@ public inline fun <T> LazyListScope.itemsIndexed(
@RequiresOptIn("This Redwood LazyLayout API is experimental and may change in the future.")
public annotation class ExperimentalRedwoodLazyLayoutApi

/**
* The horizontally scrolling list that only composes and lays out the currently visible items.
* The [content] block defines a DSL which allows you to emit items of different types. For
* example you can use [LazyListScope.item] to add a single item and [LazyListScope.items] to add
* a list of items.
*
* The purpose of [placeholder] is to define the temporary content of an on-screen item while the
* content of that item (as described by the [content] block) is being retrieved. When the content
* of that item has been retrieved, the [placeholder] is replaced with that of the content.
*
* @param state The state object to be used to control or observe the list's state.
* @param width Sets whether the row's width will wrap its contents ([Constraint.Wrap]) or match the
* width of its parent ([Constraint.Fill]).
* @param height Sets whether the row's height will wrap its contents ([Constraint.Wrap]) or match
* the height of its parent ([Constraint.Fill]).
* @param margin Applies margin (space) around the list. This can also be applied to an individual
* item using `Modifier.margin`.
* @param verticalAlignment the vertical alignment applied to the items.
* @param modifier The modifier to apply to this layout.
* @param placeholder A block which describes the content of each placeholder item. Note that the
* placeholder block will be invoked multiple times, and assumes that the content and its sizing on
* each invocation is identical to one another.
* @param content A block which describes the content. Inside this block you can use methods like
* [LazyListScope.item] to add a single item or [LazyListScope.items] to add a list of items.
*/
@Composable
public fun LazyRow(
state: LazyListState = rememberLazyListState(),
Expand All @@ -95,6 +158,38 @@ public fun LazyRow(
)
}

/**
* The horizontally scrolling list that only composes and lays out the currently visible items.
* The [content] block defines a DSL which allows you to emit items of different types. For
* example you can use [LazyListScope.item] to add a single item and [LazyListScope.items] to add
* a list of items.
*
* This function differs from the other [LazyRow] function, in that a refresh indicator is
* conditionally displayed via a vertical swipe gesture when at the beginning of the list. The
* appropriate response to this gesture can be supplied via the [onRefresh] callback.
*
* The purpose of [placeholder] is to define the temporary content of an on-screen item while the
* content of that item (as described by the [content] block) is being retrieved. When the content
* of that item has been retrieved, the [placeholder] is replaced with that of the content.
*
* @param refreshing Whether or not the list should show the pull-to-refresh indicator.
* @param onRefresh Called when a swipe gesture triggers a pull-to-refresh.
* @param state The state object to be used to control or observe the list's state.
* @param width Sets whether the row's width will wrap its contents ([Constraint.Wrap]) or match the
* width of its parent ([Constraint.Fill]).
* @param height Sets whether the row's height will wrap its contents ([Constraint.Wrap]) or match
* the height of its parent ([Constraint.Fill]).
* @param margin Applies margin (space) around the list. This can also be applied to an individual
* item using `Modifier.margin`.
* @param verticalAlignment the vertical alignment applied to the items.
* @param pullRefreshContentColor The color of the pull-to-refresh indicator.
* @param modifier The modifier to apply to this layout.
* @param placeholder A block which describes the content of each placeholder item. Note that the
* placeholder block will be invoked multiple times, and assumes that the content and its sizing on
* each invocation is identical to one another.
* @param content A block which describes the content. Inside this block you can use methods like
* [LazyListScope.item] to add a single item or [LazyListScope.items] to add a list of items.
*/
@ExperimentalRedwoodLazyLayoutApi
@Composable
public fun LazyRow(
Expand Down Expand Up @@ -126,6 +221,31 @@ public fun LazyRow(
)
}

/**
* The vertically scrolling list that only composes and lays out the currently visible items.
* The [content] block defines a DSL which allows you to emit items of different types. For
* example you can use [LazyListScope.item] to add a single item and [LazyListScope.items] to add
* a list of items.
*
* The purpose of [placeholder] is to define the temporary content of an on-screen item while the
* content of that item (as described by the [content] block) is being retrieved. When the content
* of that item has been retrieved, the [placeholder] is replaced with that of the content.
*
* @param state The state object to be used to control or observe the list's state.
* @param width Sets whether the row's width will wrap its contents ([Constraint.Wrap]) or match the
* width of its parent ([Constraint.Fill]).
* @param height Sets whether the row's height will wrap its contents ([Constraint.Wrap]) or match
* the height of its parent ([Constraint.Fill]).
* @param margin Applies margin (space) around the list. This can also be applied to an individual
* item using `Modifier.margin`.
* @param horizontalAlignment The horizontal alignment applied to the items.
* @param modifier The modifier to apply to this layout.
* @param placeholder A block which describes the content of each placeholder item. Note that the
* placeholder block will be invoked multiple times, and assumes that the content and its sizing on
* each invocation is identical to one another.
* @param content A block which describes the content. Inside this block you can use methods like
* [LazyListScope.item] to add a single item or [LazyListScope.items] to add a list of items.
*/
@Composable
public fun LazyColumn(
state: LazyListState = rememberLazyListState(),
Expand All @@ -150,6 +270,38 @@ public fun LazyColumn(
)
}

/**
* The vertically scrolling list that only composes and lays out the currently visible items.
* The [content] block defines a DSL which allows you to emit items of different types. For
* example you can use [LazyListScope.item] to add a single item and [LazyListScope.items] to add
* a list of items.
*
* This function differs from the other [LazyColumn] function, in that a refresh indicator is
* conditionally displayed via a vertical swipe gesture when at the beginning of the list. The
* appropriate response to this gesture can be supplied via the [onRefresh] callback.
*
* The purpose of [placeholder] is to define the temporary content of an on-screen item while the
* content of that item (as described by the [content] block) is being retrieved. When the content
* of that item has been retrieved, the [placeholder] is replaced with that of the content.
*
* @param refreshing Whether or not the list should show the pull-to-refresh indicator.
* @param onRefresh Called when a swipe gesture triggers a pull-to-refresh.
* @param state The state object to be used to control or observe the list's state.
* @param width Sets whether the row's width will wrap its contents ([Constraint.Wrap]) or match the
* width of its parent ([Constraint.Fill]).
* @param height Sets whether the row's height will wrap its contents ([Constraint.Wrap]) or match
* the height of its parent ([Constraint.Fill]).
* @param margin Applies margin (space) around the list. This can also be applied to an individual
* item using `Modifier.margin`.
* @param horizontalAlignment The horizontal alignment applied to the items.
* @param pullRefreshContentColor The color of the pull-to-refresh indicator.
* @param modifier The modifier to apply to this layout.
* @param placeholder A block which describes the content of each placeholder item. Note that the
* placeholder block will be invoked multiple times, and assumes that the content and its sizing on
* each invocation is identical to one another.
* @param content A block which describes the content. Inside this block you can use methods like
* [LazyListScope.item] to add a single item or [LazyListScope.items] to add a list of items.
*/
@ExperimentalRedwoodLazyLayoutApi
@Composable
public fun LazyColumn(
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,9 @@ import app.cash.redwood.lazylayout.api.ScrollItemIndex

private const val DEFAULT_PRELOAD_ITEM_COUNT = 15

/**
* Creates a [LazyListState] that is remembered across compositions.
*/
@Composable
public fun rememberLazyListState(): LazyListState {
return rememberSaveable(saver = saver) {
Expand All @@ -42,6 +45,11 @@ private val saver: Saver<LazyListState, *> = Saver(
},
)

/**
* A state object that can be hoisted to control and observe scrolling.
*
* In most cases, this will be created via [rememberLazyListState].
*/
public open class LazyListState {
/**
* Update this to trigger a programmatic scroll. This may be updated multiple times, including
Expand Down

0 comments on commit f11c70c

Please sign in to comment.