1 /*
2  * Copyright 2020 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package androidx.compose.foundation.lazy
18 
19 import androidx.annotation.FloatRange
20 import androidx.compose.animation.core.FiniteAnimationSpec
21 import androidx.compose.animation.core.Spring
22 import androidx.compose.animation.core.VisibilityThreshold
23 import androidx.compose.animation.core.spring
24 import androidx.compose.foundation.internal.JvmDefaultWithCompatibility
25 import androidx.compose.runtime.Stable
26 import androidx.compose.ui.Modifier
27 import androidx.compose.ui.unit.Constraints
28 import androidx.compose.ui.unit.IntOffset
29 
30 /** Receiver scope being used by the item content parameter of LazyColumn/Row. */
31 @Stable
32 @LazyScopeMarker
33 @JvmDefaultWithCompatibility
34 interface LazyItemScope {
35     /**
36      * Have the content fill the [Constraints.maxWidth] and [Constraints.maxHeight] of the parent
37      * measurement constraints by setting the [minimum width][Constraints.minWidth] to be equal to
38      * the [maximum width][Constraints.maxWidth] multiplied by [fraction] and the
39      * [minimum height][Constraints.minHeight] to be equal to the
40      * [maximum height][Constraints.maxHeight] multiplied by [fraction]. Note that, by default, the
41      * [fraction] is 1, so the modifier will make the content fill the whole available space.
42      * [fraction] must be between `0` and `1`.
43      *
44      * Regular [Modifier.fillMaxSize] can't work inside the scrolling layouts as the items are
45      * measured with [Constraints.Infinity] as the constraints for the main axis.
46      */
fillParentMaxSizenull47     fun Modifier.fillParentMaxSize(@FloatRange(from = 0.0, to = 1.0) fraction: Float = 1f): Modifier
48 
49     /**
50      * Have the content fill the [Constraints.maxWidth] of the parent measurement constraints by
51      * setting the [minimum width][Constraints.minWidth] to be equal to the
52      * [maximum width][Constraints.maxWidth] multiplied by [fraction]. Note that, by default, the
53      * [fraction] is 1, so the modifier will make the content fill the whole parent width.
54      * [fraction] must be between `0` and `1`.
55      *
56      * Regular [Modifier.fillMaxWidth] can't work inside the scrolling horizontally layouts as the
57      * items are measured with [Constraints.Infinity] as the constraints for the main axis.
58      */
59     fun Modifier.fillParentMaxWidth(
60         @FloatRange(from = 0.0, to = 1.0) fraction: Float = 1f
61     ): Modifier
62 
63     /**
64      * Have the content fill the [Constraints.maxHeight] of the incoming measurement constraints by
65      * setting the [minimum height][Constraints.minHeight] to be equal to the
66      * [maximum height][Constraints.maxHeight] multiplied by [fraction]. Note that, by default, the
67      * [fraction] is 1, so the modifier will make the content fill the whole parent height.
68      * [fraction] must be between `0` and `1`.
69      *
70      * Regular [Modifier.fillMaxHeight] can't work inside the scrolling vertically layouts as the
71      * items are measured with [Constraints.Infinity] as the constraints for the main axis.
72      */
73     fun Modifier.fillParentMaxHeight(
74         @FloatRange(from = 0.0, to = 1.0) fraction: Float = 1f
75     ): Modifier
76 
77     /**
78      * This modifier animates the item appearance (fade in), disappearance (fade out) and placement
79      * changes (such as an item reordering).
80      *
81      * You should also provide a key via [LazyListScope.item]/[LazyListScope.items] for this
82      * modifier to enable animations.
83      *
84      * @sample androidx.compose.foundation.samples.AnimateItemSample
85      * @param fadeInSpec an animation specs to use for animating the item appearance. When null is
86      *   provided the item will be appearing without animations.
87      * @param placementSpec an animation specs that will be used to animate the item placement.
88      *   Aside from item reordering all other position changes caused by events like arrangement or
89      *   alignment changes will also be animated. When null is provided no animations will happen.
90      * @param fadeOutSpec an animation specs to use for animating the item disappearance. When null
91      *   is provided the item will be disappearance without animations.
92      */
93     fun Modifier.animateItem(
94         fadeInSpec: FiniteAnimationSpec<Float>? = spring(stiffness = Spring.StiffnessMediumLow),
95         placementSpec: FiniteAnimationSpec<IntOffset>? =
96             spring(
97                 stiffness = Spring.StiffnessMediumLow,
98                 visibilityThreshold = IntOffset.VisibilityThreshold
99             ),
100         fadeOutSpec: FiniteAnimationSpec<Float>? = spring(stiffness = Spring.StiffnessMediumLow),
101     ): Modifier = this
102 }
103