PagerDefaults


Contains the default values used by Pager.

Summary

Constants

const Int

The default value of beyondViewportPageCount used to specify the number of pages to compose and layout before and after the visible pages.

Cmn

Public functions

TargetedFlingBehavior
@Composable
flingBehavior(
    state: PagerState,
    pagerSnapDistance: PagerSnapDistance,
    decayAnimationSpec: DecayAnimationSpec<Float>,
    snapAnimationSpec: AnimationSpec<Float>,
    snapPositionalThreshold: @FloatRange(from = 0.0, to = 1.0) Float
)

A snapFlingBehavior that will snap pages to the start of the layout.

Cmn
NestedScrollConnection

The default implementation of Pager's pageNestedScrollConnection.

Cmn

Constants

BeyondViewportPageCount

const val BeyondViewportPageCount = 0: Int

The default value of beyondViewportPageCount used to specify the number of pages to compose and layout before and after the visible pages. It does not include the pages automatically composed and laid out by the pre-fetcher in the direction of the scroll during scroll events.

Public functions

flingBehavior

@Composable
fun flingBehavior(
    state: PagerState,
    pagerSnapDistance: PagerSnapDistance = PagerSnapDistance.atMost(1),
    decayAnimationSpec: DecayAnimationSpec<Float> = rememberSplineBasedDecay(),
    snapAnimationSpec: AnimationSpec<Float> = spring( stiffness = Spring.StiffnessMediumLow, visibilityThreshold = Int.VisibilityThreshold.toFloat() ),
    snapPositionalThreshold: @FloatRange(from = 0.0, to = 1.0) Float = 0.5f
): TargetedFlingBehavior

A snapFlingBehavior that will snap pages to the start of the layout. One can use the given parameters to control how the snapping animation will happen.

Parameters
state: PagerState

The PagerState that controls the which to which this FlingBehavior will be applied to.

pagerSnapDistance: PagerSnapDistance = PagerSnapDistance.atMost(1)

A way to control the snapping destination for this Pager. The default behavior will result in any fling going to the next page in the direction of the fling (if the fling has enough velocity, otherwise the Pager will bounce back). Use PagerSnapDistance.atMost to define a maximum number of pages this Pager is allowed to fling after scrolling is finished and fling has started.

decayAnimationSpec: DecayAnimationSpec<Float> = rememberSplineBasedDecay()

The animation spec used to approach the target offset. When the fling velocity is large enough. Large enough means large enough to naturally decay. For single page snapping this usually never happens since there won't be enough space to run a decay animation.

snapAnimationSpec: AnimationSpec<Float> = spring( stiffness = Spring.StiffnessMediumLow, visibilityThreshold = Int.VisibilityThreshold.toFloat() )

The animation spec used to finally snap to the position. This animation will be often used in 2 cases: 1) There was enough space to an approach animation, the Pager will use snapAnimationSpec in the last step of the animation to settle the page into position. 2) There was not enough space to run the approach animation.

snapPositionalThreshold: @FloatRange(from = 0.0, to = 1.0) Float = 0.5f

If the fling has a low velocity (e.g. slow scroll), this fling behavior will use this snap threshold in order to determine if the pager should snap back or move forward. Use a number between 0 and 1 as a fraction of the page size that needs to be scrolled before the Pager considers it should move to the next page. For instance, if snapPositionalThreshold = 0.35, it means if this pager is scrolled with a slow velocity and the Pager scrolls more than 35% of the page size, then will jump to the next page, if not it scrolls back. Note that any fling that has high enough velocity will always move to the next page in the direction of the fling.

Returns
TargetedFlingBehavior

An instance of FlingBehavior that will perform Snapping to the next page by default. The animation will be governed by the post scroll velocity and the Pager will use either snapAnimationSpec or decayAnimationSpec to approach the snapped position If a velocity is not high enough the pager will use snapAnimationSpec to reach the snapped position. If the velocity is high enough, the Pager will use the logic described in decayAnimationSpec and snapAnimationSpec.

See also
snapFlingBehavior

for more information on what which parameter controls in the overall snapping animation.

The animation specs used by the fling behavior will depend on 2 factors:

  1. The gesture velocity.

  2. The target page proposed by pagerSnapDistance.

If you're using single page snapping (the most common use case for Pager), there won't be enough space to actually run a decay animation to approach the target page, so the Pager will always use the snapping animation from snapAnimationSpec. If you're using multi-page snapping (this means you're abs(targetPage - currentPage) 1) the Pager may use decayAnimationSpec or snapAnimationSpec to approach the targetPage, it will depend on the velocity generated by the triggering gesture. If the gesture has a high enough velocity to approach the target page, the Pager will use decayAnimationSpec followed by snapAnimationSpec for the final step of the animation. If the gesture doesn't have enough velocity, the Pager will use snapAnimationSpec + snapAnimationSpec in a similar fashion.

pageNestedScrollConnection

@Composable
fun pageNestedScrollConnection(state: PagerState, orientation: Orientation): NestedScrollConnection

The default implementation of Pager's pageNestedScrollConnection.

Parameters
state: PagerState

state of the pager

orientation: Orientation

The orientation of the pager. This will be used to determine which direction the nested scroll connection will operate and react on.