ScalingParams
interface ScalingParams
Parameters to control the scaling of the contents of 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. There are two symmetrical transition lines/areas one at the top of the viewport and one at the bottom.
The items transition line is based upon its size with the potential for larger list items to start their transition earlier (further from the edge they are transitioning towards) than smaller items.
It is possible for the transition line to be closer to the edge that the list item is moving away from, i.e. the opposite side of the center line of the viewport. This may seem counter-intuitive at first as it means that the transition lines can appear inverted. But as the two transition lines interact with the opposite edges of the list item top with bottom, bottom with top it is often desirable to have inverted transition lines for large list 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.
Summary
Public functions |
|
|---|---|
Int |
resolveViewportVerticalOffset(viewportConstraints: Constraints)The additional padding to consider above and below the viewport of a |
Public properties |
|
|---|---|
Float |
What fraction of the full transparency of the item to draw it with when closest to the edge of the screen. |
Float |
What fraction of the full size of the item to scale it by when most scaled, e.g. at the edge of the viewport. |
Float |
The maximum element height as a ratio of the viewport size to use for determining the transition point within ( |
Float |
The upper bound of the transition line area, closest to the center of the viewport. |
Float |
The maximum element height as a ratio of the viewport size to use for determining the transition point within ( |
Float |
The lower bound of the transition line area, closest to the edge of the viewport. |
Easing |
An interpolator to use to determine how to apply scaling as a item transitions across the scaling transition area. |
Public functions
resolveViewportVerticalOffset
fun resolveViewportVerticalOffset(viewportConstraints: Constraints): Int
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 20% of the maxHeight of the viewport above and below the content.
| Parameters | |
|---|---|
viewportConstraints: Constraints |
the viewports constraints |
Public properties
edgeAlpha
val edgeAlpha: Float
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.
edgeScale
val edgeScale: Float
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.
maxElementHeight
val maxElementHeight: Float
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.
maxTransitionArea
val maxTransitionArea: Float
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.
For transition lines a value of 0f means that the transition line is at the viewport edge, e.g. no transition, a value of 0.25f means that the transition line is 25% of the screen size away from the viewport edge. A value of .5f or greater will place the transition line in the other half of the screen to the edge that the item is transitioning towards.
minTransitionArea and maxTransitionArea provide an area in which transition lines for all list items exist. Depending on the size of the list item the specific point in the area is calculated.
minElementHeight
val minElementHeight: Float
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
val minTransitionArea: Float
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.
For transition lines a value of 0f means that the transition line is at the viewport edge, e.g. no transition, a value of 0.25f means that the transition line is 25% of the screen size away from the viewport edge. A value of .5f or greater will place the transition line in the other half of the screen to the edge that the item is transitioning towards.
minTransitionArea and maxTransitionArea provide an area in which transition lines for all list items exist. Depending on the size of the list item the specific point in the area is calculated.
scaleInterpolator
val scaleInterpolator: Easing
An interpolator to use to determine how to apply scaling as a item transitions across the scaling transition area.