glance/glance-appwidget/src/main/java/androidx/glance/appwidget/lazy/LazyList.kt - platform/frameworks/support - Git at Google

 /*
  * Copyright 2021 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package androidx.glance.appwidget.lazy

 import android.os.Bundle
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.key
 import androidx.glance.Emittable
 import androidx.glance.EmittableLazyItemWithChildren
 import androidx.glance.EmittableWithChildren
 import androidx.glance.ExperimentalGlanceApi
 import androidx.glance.GlanceModifier
 import androidx.glance.GlanceNode
 import androidx.glance.layout.Alignment
 import androidx.glance.layout.fillMaxWidth
 import androidx.glance.layout.wrapContentHeight

 /**
  * A vertical scrolling list that only lays out the currently visible items. The [content] block
  * defines a DSL which allows you to emit different list items.
  *
  * @param modifier the modifier to apply to this layout
  * @param horizontalAlignment the horizontal alignment applied to the items.
  * @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. If the
  * item has more than one top-level child, they will be automatically wrapped in a Box.
  */
 // TODO(b/198618359): interaction handling
 @Composable
 fun LazyColumn(
  modifier: GlanceModifier = GlanceModifier,
  horizontalAlignment: Alignment.Horizontal = Alignment.Start,
  content: LazyListScope.() -> Unit
 ) {
  GlanceNode(
  factory = ::EmittableLazyColumn,
  update = {
  this.set(modifier) { this.modifier = it }
  this.set(horizontalAlignment) { this.horizontalAlignment = it }
  },
  content = applyListScope(
  Alignment(horizontalAlignment, Alignment.Vertical.CenterVertically),
  content
  )
  )
 }

 /**
  * A vertical scrolling list that only lays out the currently visible items. The [content] block
  * defines a DSL which allows you to emit different list items.
  *
  * @param activityOptions Additional options built from an [android.app.ActivityOptions] to apply to
  * an activity start.
  * @param modifier the modifier to apply to this layout
  * @param horizontalAlignment the horizontal alignment applied to the items.
  * @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. If the
  * item has more than one top-level child, they will be automatically wrapped in a Box.
  */
 @ExperimentalGlanceApi
 @Composable
 fun LazyColumn(
  activityOptions: Bundle,
  modifier: GlanceModifier = GlanceModifier,
  horizontalAlignment: Alignment.Horizontal = Alignment.Start,
  content: LazyListScope.() -> Unit
 ) {
  GlanceNode(
  factory = ::EmittableLazyColumn,
  update = {
  this.set(modifier) { this.modifier = it }
  this.set(horizontalAlignment) { this.horizontalAlignment = it }
  this.set(activityOptions) { this.activityOptions = it }
  },
  content = applyListScope(
  Alignment(horizontalAlignment, Alignment.Vertical.CenterVertically),
  content
  )
  )
 }

 private fun applyListScope(
  alignment: Alignment,
  content: LazyListScope.() -> Unit
 ): @Composable () -> Unit {
  val itemList = mutableListOf<Pair<Long?, @Composable LazyItemScope.() -> Unit>>()
  val listScopeImpl = object : LazyListScope {
  override fun item(itemId: Long, content: @Composable LazyItemScope.() -> Unit) {
  require(itemId == LazyListScope.UnspecifiedItemId || itemId > ReservedItemIdRangeEnd) {
  """
  You may not specify item ids less than $ReservedItemIdRangeEnd in a Glance
  widget. These are reserved.
  """.trimIndent()
  }
  itemList.add(itemId to content)
  }

  override fun items(
  count: Int,
  itemId: ((index: Int) -> Long),
  itemContent: @Composable LazyItemScope.(index: Int) -> Unit
  ) {
  repeat(count) { index ->
  item(itemId(index)) { itemContent(index) }
  }
  }
  }
  listScopeImpl.apply(content)
  return {
  itemList.forEachIndexed { index, (itemId, composable) ->
  val id = itemId.takeIf { it != LazyListScope.UnspecifiedItemId }
  ?: (ReservedItemIdRangeEnd - index)
  check(id != LazyListScope.UnspecifiedItemId) { "Implicit list item ids exhausted." }
  LazyListItem(id, alignment) {
  object : LazyItemScope { }.composable()
  }
  }
  }
 }

 @Composable
 private fun LazyListItem(
  itemId: Long,
  alignment: Alignment,
  content: @Composable () -> Unit
 ) {
  // We wrap LazyListItem in the key composable to ensure that lambda actions declared within each
  // item's scope will get a unique ID based on the currentCompositeKeyHash.
  key(itemId) {
  GlanceNode(
  factory = ::EmittableLazyListItem,
  update = {
  this.set(itemId) { this.itemId = it }
  this.set(alignment) { this.alignment = it }
  },
  content = content
  )
  }
 }

 /**
  * Values between -2^63 and -2^62 are reserved for list items whose id has not been explicitly
  * defined.
  */
 internal const val ReservedItemIdRangeEnd = -0x4_000_000_000_000_000L

 @DslMarker
 annotation class LazyScopeMarker

 /**
  * Receiver scope being used by the item content parameter of [LazyColumn].
  */
 @LazyScopeMarker
 interface LazyItemScope

 @JvmDefaultWithCompatibility
 /**
  * Receiver scope which is used by [LazyColumn].
  */
 @LazyScopeMarker
 interface LazyListScope {
  /**
  * Adds a single item.
  *
  * @param itemId a stable and unique id representing the item. The value may not be less than
  * or equal to -2^62, as these values are reserved by the Glance API. Specifying the list
  * item ids will maintain the scroll position through app widget updates in Android S and
  * higher devices.
  * @param content the content of the item
  */
  fun item(itemId: Long = UnspecifiedItemId, content: @Composable LazyItemScope.() -> Unit)

  /**
  * Adds a [count] of items.
  *
  * @param count the count of items
  * @param itemId a factory of stable and unique ids representing the item. The value may not be
  * less than or equal to -2^62, as these values are reserved by the Glance API. Specifying
  * the list item ids will maintain the scroll position through app widget updates in Android
  * S and higher devices.
  * @param itemContent the content displayed by a single item
  */
  fun items(
  count: Int,
  itemId: ((index: Int) -> Long) = { UnspecifiedItemId },
  itemContent: @Composable LazyItemScope.(index: Int) -> Unit
  )

  companion object {
  const val UnspecifiedItemId = Long.MIN_VALUE
  }
 }

 /**
  * Adds a list of items.
  *
  * @param items the data list
  * @param itemId a factory of stable and unique ids representing the item. The value may not be
  * less than or equal to -2^62, as these values are reserved by the Glance API. Specifying
  * the list item ids will maintain the scroll position through app widget updates in Android
  * S and higher devices.
  * @param itemContent the content displayed by a single item
  */
 inline fun <T> LazyListScope.items(
  items: List<T>,
  crossinline itemId: ((item: T) -> Long) = { LazyListScope.UnspecifiedItemId },
  crossinline itemContent: @Composable LazyItemScope.(item: T) -> Unit
 ) = items(items.size, { index: Int -> itemId(items[index]) }) {
  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 itemId a factory of stable and unique ids representing the item. The value may not be
  * less than or equal to -2^62, as these values are reserved by the Glance API. Specifying
  * the list item ids will maintain the scroll position through app widget updates in Android
  * S and higher devices.
  * @param itemContent the content displayed by a single item
  */
 inline fun <T> LazyListScope.itemsIndexed(
  items: List<T>,
  crossinline itemId: ((index: Int, item: T) -> Long) =
  { _, _ -> LazyListScope.UnspecifiedItemId },
  crossinline itemContent: @Composable LazyItemScope.(index: Int, item: T) -> Unit
 ) = items(items.size, { index: Int -> itemId(index, items[index]) }) {
  itemContent(it, items[it])
 }

 /**
  * Adds an array of items.
  *
  * @param items the data array
  * @param itemId a factory of stable and unique list item ids. Using the same itemId for multiple
  * items in the array is not allowed. When you specify the itemId, the scroll position will be
  * maintained based on the itemId, which means if you add/remove items before the current visible
  * item the item with the given itemId will be kept as the first visible one.
  * @param itemContent the content displayed by a single item
  */
 inline fun <T> LazyListScope.items(
  items: Array<T>,
  noinline itemId: ((item: T) -> Long) = { LazyListScope.UnspecifiedItemId },
  crossinline itemContent: @Composable LazyItemScope.(item: T) -> Unit
 ) = items(items.size, { index: Int -> itemId(items[index]) }) {
  itemContent(items[it])
 }

 /**
  * Adds a array of items where the content of an item is aware of its index.
  *
  * @param items the data array
  * @param itemId a factory of stable and unique list item ids. Using the same itemId for multiple
  * items in the array is not allowed. When you specify the itemId the scroll position will be
  * maintained based on the itemId, which means if you add/remove items before the current visible
  * item the item with the given itemId will be kept as the first visible one.
  * @param itemContent the content displayed by a single item
  */
 inline fun <T> LazyListScope.itemsIndexed(
  items: Array<T>,
  noinline itemId: ((index: Int, item: T) -> Long) = { _, _ -> LazyListScope.UnspecifiedItemId },
  crossinline itemContent: @Composable LazyItemScope.(index: Int, item: T) -> Unit
 ) = items(items.size, { index: Int -> itemId(index, items[index]) }) {
  itemContent(it, items[it])
 }

 internal abstract class EmittableLazyList : EmittableWithChildren(resetsDepthForChildren = true) {
  override var modifier: GlanceModifier = GlanceModifier
  var horizontalAlignment: Alignment.Horizontal = Alignment.Start
  var activityOptions: Bundle? = null

  override fun toString() =
  "EmittableLazyList(modifier=$modifier, horizontalAlignment=$horizontalAlignment, " +
  "activityOptions=$activityOptions, children=[\n${childrenToString()}\n])"
 }

 internal class EmittableLazyListItem : EmittableLazyItemWithChildren() {
  // Fill max width of the lazy column so that item contents can be aligned per the horizontal
  // alignment.
  override var modifier: GlanceModifier = GlanceModifier.wrapContentHeight().fillMaxWidth()
  var itemId: Long = 0

  override fun copy(): Emittable = EmittableLazyListItem().also {
  it.itemId = itemId
  it.alignment = alignment
  it.children.addAll(children.map { it.copy() })
  }

  override fun toString() =
  "EmittableLazyListItem(modifier=$modifier, alignment=$alignment, " +
  "children=[\n${childrenToString()}\n])"
 }

 internal class EmittableLazyColumn : EmittableLazyList() {
  override fun copy(): Emittable = EmittableLazyColumn().also {
  it.modifier = modifier
  it.horizontalAlignment = horizontalAlignment
  it.activityOptions = activityOptions
  it.children.addAll(children.map { it.copy() })
  }
 }
	/*
	* Copyright 2021 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package androidx.glance.appwidget.lazy

	import android.os.Bundle
	import androidx.compose.runtime.Composable
	import androidx.compose.runtime.key
	import androidx.glance.Emittable
	import androidx.glance.EmittableLazyItemWithChildren
	import androidx.glance.EmittableWithChildren
	import androidx.glance.ExperimentalGlanceApi
	import androidx.glance.GlanceModifier
	import androidx.glance.GlanceNode
	import androidx.glance.layout.Alignment
	import androidx.glance.layout.fillMaxWidth
	import androidx.glance.layout.wrapContentHeight

	/**
	* A vertical scrolling list that only lays out the currently visible items. The [content] block
	* defines a DSL which allows you to emit different list items.
	*
	* @param modifier the modifier to apply to this layout
	* @param horizontalAlignment the horizontal alignment applied to the items.
	* @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. If the
	* item has more than one top-level child, they will be automatically wrapped in a Box.
	*/
	// TODO(b/198618359): interaction handling
	@Composable
	fun LazyColumn(
	modifier: GlanceModifier = GlanceModifier,
	horizontalAlignment: Alignment.Horizontal = Alignment.Start,
	content: LazyListScope.() -> Unit
	) {
	GlanceNode(
	factory = ::EmittableLazyColumn,
	update = {
	this.set(modifier) { this.modifier = it }
	this.set(horizontalAlignment) { this.horizontalAlignment = it }
	},
	content = applyListScope(
	Alignment(horizontalAlignment, Alignment.Vertical.CenterVertically),
	content
	)
	)
	}

	/**
	* A vertical scrolling list that only lays out the currently visible items. The [content] block
	* defines a DSL which allows you to emit different list items.
	*
	* @param activityOptions Additional options built from an [android.app.ActivityOptions] to apply to
	* an activity start.
	* @param modifier the modifier to apply to this layout
	* @param horizontalAlignment the horizontal alignment applied to the items.
	* @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. If the
	* item has more than one top-level child, they will be automatically wrapped in a Box.
	*/
	@ExperimentalGlanceApi
	@Composable
	fun LazyColumn(
	activityOptions: Bundle,
	modifier: GlanceModifier = GlanceModifier,
	horizontalAlignment: Alignment.Horizontal = Alignment.Start,
	content: LazyListScope.() -> Unit
	) {
	GlanceNode(
	factory = ::EmittableLazyColumn,
	update = {
	this.set(modifier) { this.modifier = it }
	this.set(horizontalAlignment) { this.horizontalAlignment = it }
	this.set(activityOptions) { this.activityOptions = it }
	},
	content = applyListScope(
	Alignment(horizontalAlignment, Alignment.Vertical.CenterVertically),
	content
	)
	)
	}

	private fun applyListScope(
	alignment: Alignment,
	content: LazyListScope.() -> Unit
	): @Composable () -> Unit {
	val itemList = mutableListOf<Pair<Long?, @Composable LazyItemScope.() -> Unit>>()
	val listScopeImpl = object : LazyListScope {
	override fun item(itemId: Long, content: @Composable LazyItemScope.() -> Unit) {
	require(itemId == LazyListScope.UnspecifiedItemId \|\| itemId > ReservedItemIdRangeEnd) {
	"""
	You may not specify item ids less than $ReservedItemIdRangeEnd in a Glance
	widget. These are reserved.
	""".trimIndent()
	}
	itemList.add(itemId to content)
	}

	override fun items(
	count: Int,
	itemId: ((index: Int) -> Long),
	itemContent: @Composable LazyItemScope.(index: Int) -> Unit
	) {
	repeat(count) { index ->
	item(itemId(index)) { itemContent(index) }
	}
	}
	}
	listScopeImpl.apply(content)
	return {
	itemList.forEachIndexed { index, (itemId, composable) ->
	val id = itemId.takeIf { it != LazyListScope.UnspecifiedItemId }
	?: (ReservedItemIdRangeEnd - index)
	check(id != LazyListScope.UnspecifiedItemId) { "Implicit list item ids exhausted." }
	LazyListItem(id, alignment) {
	object : LazyItemScope { }.composable()
	}
	}
	}
	}

	@Composable
	private fun LazyListItem(
	itemId: Long,
	alignment: Alignment,
	content: @Composable () -> Unit
	) {
	// We wrap LazyListItem in the key composable to ensure that lambda actions declared within each
	// item's scope will get a unique ID based on the currentCompositeKeyHash.
	key(itemId) {
	GlanceNode(
	factory = ::EmittableLazyListItem,
	update = {
	this.set(itemId) { this.itemId = it }
	this.set(alignment) { this.alignment = it }
	},
	content = content
	)
	}
	}

	/**
	* Values between -2^63 and -2^62 are reserved for list items whose id has not been explicitly
	* defined.
	*/
	internal const val ReservedItemIdRangeEnd = -0x4_000_000_000_000_000L

	@DslMarker
	annotation class LazyScopeMarker

	/**
	* Receiver scope being used by the item content parameter of [LazyColumn].
	*/
	@LazyScopeMarker
	interface LazyItemScope

	@JvmDefaultWithCompatibility
	/**
	* Receiver scope which is used by [LazyColumn].
	*/
	@LazyScopeMarker
	interface LazyListScope {
	/**
	* Adds a single item.
	*
	* @param itemId a stable and unique id representing the item. The value may not be less than
	* or equal to -2^62, as these values are reserved by the Glance API. Specifying the list
	* item ids will maintain the scroll position through app widget updates in Android S and
	* higher devices.
	* @param content the content of the item
	*/
	fun item(itemId: Long = UnspecifiedItemId, content: @Composable LazyItemScope.() -> Unit)

	/**
	* Adds a [count] of items.
	*
	* @param count the count of items
	* @param itemId a factory of stable and unique ids representing the item. The value may not be
	* less than or equal to -2^62, as these values are reserved by the Glance API. Specifying
	* the list item ids will maintain the scroll position through app widget updates in Android
	* S and higher devices.
	* @param itemContent the content displayed by a single item
	*/
	fun items(
	count: Int,
	itemId: ((index: Int) -> Long) = { UnspecifiedItemId },
	itemContent: @Composable LazyItemScope.(index: Int) -> Unit
	)

	companion object {
	const val UnspecifiedItemId = Long.MIN_VALUE
	}
	}

	/**
	* Adds a list of items.
	*
	* @param items the data list
	* @param itemId a factory of stable and unique ids representing the item. The value may not be
	* less than or equal to -2^62, as these values are reserved by the Glance API. Specifying
	* the list item ids will maintain the scroll position through app widget updates in Android
	* S and higher devices.
	* @param itemContent the content displayed by a single item
	*/
	inline fun <T> LazyListScope.items(
	items: List<T>,
	crossinline itemId: ((item: T) -> Long) = { LazyListScope.UnspecifiedItemId },
	crossinline itemContent: @Composable LazyItemScope.(item: T) -> Unit
	) = items(items.size, { index: Int -> itemId(items[index]) }) {
	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 itemId a factory of stable and unique ids representing the item. The value may not be
	* less than or equal to -2^62, as these values are reserved by the Glance API. Specifying
	* the list item ids will maintain the scroll position through app widget updates in Android
	* S and higher devices.
	* @param itemContent the content displayed by a single item
	*/
	inline fun <T> LazyListScope.itemsIndexed(
	items: List<T>,
	crossinline itemId: ((index: Int, item: T) -> Long) =
	{ _, _ -> LazyListScope.UnspecifiedItemId },
	crossinline itemContent: @Composable LazyItemScope.(index: Int, item: T) -> Unit
	) = items(items.size, { index: Int -> itemId(index, items[index]) }) {
	itemContent(it, items[it])
	}

	/**
	* Adds an array of items.
	*
	* @param items the data array
	* @param itemId a factory of stable and unique list item ids. Using the same itemId for multiple
	* items in the array is not allowed. When you specify the itemId, the scroll position will be
	* maintained based on the itemId, which means if you add/remove items before the current visible
	* item the item with the given itemId will be kept as the first visible one.
	* @param itemContent the content displayed by a single item
	*/
	inline fun <T> LazyListScope.items(
	items: Array<T>,
	noinline itemId: ((item: T) -> Long) = { LazyListScope.UnspecifiedItemId },
	crossinline itemContent: @Composable LazyItemScope.(item: T) -> Unit
	) = items(items.size, { index: Int -> itemId(items[index]) }) {
	itemContent(items[it])
	}

	/**
	* Adds a array of items where the content of an item is aware of its index.
	*
	* @param items the data array
	* @param itemId a factory of stable and unique list item ids. Using the same itemId for multiple
	* items in the array is not allowed. When you specify the itemId the scroll position will be
	* maintained based on the itemId, which means if you add/remove items before the current visible
	* item the item with the given itemId will be kept as the first visible one.
	* @param itemContent the content displayed by a single item
	*/
	inline fun <T> LazyListScope.itemsIndexed(
	items: Array<T>,
	noinline itemId: ((index: Int, item: T) -> Long) = { _, _ -> LazyListScope.UnspecifiedItemId },
	crossinline itemContent: @Composable LazyItemScope.(index: Int, item: T) -> Unit
	) = items(items.size, { index: Int -> itemId(index, items[index]) }) {
	itemContent(it, items[it])
	}

	internal abstract class EmittableLazyList : EmittableWithChildren(resetsDepthForChildren = true) {
	override var modifier: GlanceModifier = GlanceModifier
	var horizontalAlignment: Alignment.Horizontal = Alignment.Start
	var activityOptions: Bundle? = null

	override fun toString() =
	"EmittableLazyList(modifier=$modifier, horizontalAlignment=$horizontalAlignment, " +
	"activityOptions=$activityOptions, children=[\n${childrenToString()}\n])"
	}

	internal class EmittableLazyListItem : EmittableLazyItemWithChildren() {
	// Fill max width of the lazy column so that item contents can be aligned per the horizontal
	// alignment.
	override var modifier: GlanceModifier = GlanceModifier.wrapContentHeight().fillMaxWidth()
	var itemId: Long = 0

	override fun copy(): Emittable = EmittableLazyListItem().also {
	it.itemId = itemId
	it.alignment = alignment
	it.children.addAll(children.map { it.copy() })
	}

	override fun toString() =
	"EmittableLazyListItem(modifier=$modifier, alignment=$alignment, " +
	"children=[\n${childrenToString()}\n])"
	}

	internal class EmittableLazyColumn : EmittableLazyList() {
	override fun copy(): Emittable = EmittableLazyColumn().also {
	it.modifier = modifier
	it.horizontalAlignment = horizontalAlignment
	it.activityOptions = activityOptions
	it.children.addAll(children.map { it.copy() })
	}
	}