ScalingLazyColumnDefaults

object ScalingLazyColumnDefaults


Contains the default values used by ScalingLazyColumn

Summary

Public functions

ScalingParams
scalingParams(
    edgeScale: Float,
    edgeAlpha: Float,
    minElementHeight: Float,
    maxElementHeight: Float,
    minTransitionArea: Float,
    maxTransitionArea: Float,
    scaleInterpolator: Easing,
    viewportVerticalOffsetResolver: (Constraints) -> Int
)

Creates a ScalingParams that represents the scaling and alpha properties for a ScalingLazyColumn.

FlingBehavior
@Composable
snapFlingBehavior(
    state: ScalingLazyListState,
    snapOffset: Dp,
    decay: DecayAnimationSpec<Float>
)

Create and remember a FlingBehavior that will represent natural fling curve with snap to central item as the fling decays.

Public functions

scalingParams

Added in 1.2.0
fun scalingParams(
    edgeScale: Float = 0.7f,
    edgeAlpha: Float = 0.5f,
    minElementHeight: Float = 0.2f,
    maxElementHeight: Float = 0.6f,
    minTransitionArea: Float = 0.35f,
    maxTransitionArea: Float = 0.55f,
    scaleInterpolator: Easing = CubicBezierEasing(0.3f, 0f, 0.7f, 1f),
    viewportVerticalOffsetResolver: (Constraints) -> Int = { (it.maxHeight / 20f).toInt() }
): ScalingParams

Creates a ScalingParams that represents the scaling and alpha properties for a ScalingLazyColumn.

Items in the ScalingLazyColumn have scaling and alpha effects applied to them depending on their position in the viewport. The closer to the edge (top or bottom) of the viewport that they are the greater the down scaling and transparency that is applied. Note that scaling and transparency effects are applied from the center of the viewport (nearest to full size and normal transparency) towards the edge (items can be smaller and more transparent).

Deciding how much scaling and alpha to apply is based on the position and size of the item and on a series of properties that are used to determine the transition area for each item.

The transition area is defined by the edge of the screen and a transition line which is calculated for each item in the list. The items transition line is based upon its size with the potential for larger list items to start their transition earlier (closer to the center) than smaller items.

minTransitionArea and maxTransitionArea are both in the range 0f..1f and are the fraction of the distance between the edges of the viewport. E.g. a value of 0.2f for minTransitionArea and 0.75f for maxTransitionArea determines that all transition lines will fall between 1/5th (20%) and 3/4s (75%) of the height of the viewport.

The size of the each item is used to determine where within the transition area range minTransitionArea..maxTransitionArea the actual transition line will be. minElementHeight and maxElementHeight are used along with the item height (as a fraction of the viewport height in the range 0f..1f) to find the transition line. So if the items size is 0.25f (25%) of way between minElementSize..maxElementSize then the transition line will be 0.25f (25%) of the way between minTransitionArea..maxTransitionArea.

A list item smaller than minElementHeight is rounded up to minElementHeight and larger than maxElementHeight is rounded down to maxElementHeight. Whereabouts the items height sits between minElementHeight..maxElementHeight is then used to determine where the transition line sits between minTransitionArea..maxTransition area.

If an item is smaller than or equal to minElementSize its transition line with be at minTransitionArea and if it is larger than or equal to maxElementSize its transition line will be at maxTransitionArea.

For example, if we take the default values for minTransitionArea = 0.2f and maxTransitionArea = 0.6f and minElementSize = 0.2f and maxElementSize= 0.8f then an item with a height of 0.4f (40%) of the viewport height is one third of way between minElementSize and maxElementSize, (0.4f - 0.2f) / (0.8f - 0.2f) = 0.33f. So its transition line would be one third of way between 0.2f and 0.6f, transition line = 0.2f + (0.6f - 0.2f) * 0.33f = 0.33f.

Once the position of the transition line is established we now have a transition area for the item, e.g. in the example above the item will start/finish its transitions when it is 0.33f (33%) of the distance from the edge of the viewport and will start/finish its transitions at the viewport edge.

The scaleInterpolator is used to determine how much of the scaling and alpha to apply as the item transits through the transition area.

The edge of the item furthest from the edge of the screen is used as a scaling trigger point for each item.

Parameters
edgeScale: Float = 0.7f

What fraction of the full size of the item to scale it by when most scaled, e.g. at the edge of the viewport. A value between 0f,1f, so a value of 0.2f means to scale an item to 20% of its normal size.

edgeAlpha: Float = 0.5f

What fraction of the full transparency of the item to draw it with when closest to the edge of the screen. A value between 0f,1f, so a value of 0.2f means to set the alpha of an item to 20% of its normal value.

minElementHeight: Float = 0.2f

The minimum element height as a ratio of the viewport size to use for determining the transition point within (minTransitionArea, maxTransitionArea) that a given content item will start to be transitioned. Items smaller than minElementHeight will be treated as if minElementHeight. Must be less than or equal to maxElementHeight.

maxElementHeight: Float = 0.6f

The maximum element height as a ratio of the viewport size to use for determining the transition point within (minTransitionArea, maxTransitionArea) that a given content item will start to be transitioned. Items larger than maxElementHeight will be treated as if maxElementHeight. Must be greater than or equal to minElementHeight.

minTransitionArea: Float = 0.35f

The lower bound of the transition line area, closest to the edge of the viewport. Defined as a fraction (value between 0f..1f) of the distance between the viewport edges. Must be less than or equal to maxTransitionArea.

maxTransitionArea: Float = 0.55f

The upper bound of the transition line area, closest to the center of the viewport. The fraction (value between 0f..1f) of the distance between the viewport edges. Must be greater than or equal to minTransitionArea.

scaleInterpolator: Easing = CubicBezierEasing(0.3f, 0f, 0.7f, 1f)

An interpolator to use to determine how to apply scaling as a item transitions across the scaling transition area.

viewportVerticalOffsetResolver: (Constraints) -> Int = { (it.maxHeight / 20f).toInt() }

The additional padding to consider above and below the viewport of a ScalingLazyColumn when considering which items to draw in the viewport. If set to 0 then no additional padding will be provided and only the items which would appear in the viewport before any scaling is applied will be considered for drawing, this may leave blank space at the top and bottom of the viewport where the next available item could have been drawn once other items have been scaled down in size. The larger this value is set to will allow for more content items to be considered for drawing in the viewport, however there is a performance cost associated with materializing items that are subsequently not drawn. The higher/more extreme the scaling parameters that are applied to the ScalingLazyColumn the more padding may be needed to ensure there are always enough content items available to be rendered. By default will be 5% of the maxHeight of the viewport above and below the content.

snapFlingBehavior

@Composable
fun snapFlingBehavior(
    state: ScalingLazyListState,
    snapOffset: Dp = 0.dp,
    decay: DecayAnimationSpec<Float> = exponentialDecay()
): FlingBehavior

Create and remember a FlingBehavior that will represent natural fling curve with snap to central item as the fling decays.

Parameters
state: ScalingLazyListState

the state of the ScalingLazyColumn

snapOffset: Dp = 0.dp

an optional offset to be applied when snapping the item. After the snap the snapped items offset will be snapOffset.

decay: DecayAnimationSpec<Float> = exponentialDecay()

the decay to use