GlimmerPagerState

public class GlimmerPagerState
@RememberInComposition
constructor(
    @IntRange(from = 0) currentPage: Int = 0,
    @FloatRange(from = -0.5, to = 0.5) currentPageOffsetFraction: Float = 0f,
    pageCount: () -> Int,
) : ScrollableState

The state that can be used to control GlimmerHorizontalPager.

Parameters

Properties

pageCount

public val pageCount: Int

The total amount of pages present in this pager.

layoutInfo

public val layoutInfo: GlimmerPagerLayoutInfo

A GlimmerPagerLayoutInfo that contains information about the Pager's last layout pass.

interactionSource

public val interactionSource: InteractionSource

InteractionSource that will be used to dispatch drag events when this pager is being dragged. If you want to know whether the fling (or animated scroll) is in progress, use isScrollInProgress.

currentPage

public val currentPage: Int

The page that sits closest to the snapped position. This is an observable value and will change as the pager scrolls either by gesture or animation.

currentPageOffsetFraction

public val currentPageOffsetFraction: Float

Indicates how far the current page is to the snapped position, this will vary from -0.5 (page is offset towards the start of the layout) to 0.5 (page is offset towards the end of the layout). This is 0.0 if the currentPage is in the snapped position. The value will flip once the current page changes.

settledPage

public val settledPage: Int

The page that is currently "settled". This is an animation/gesture unaware page in the sense that it will not be updated while the pages are being scrolled, but rather when the animation/scroll settles.

targetPage

public val targetPage: Int

The page that is currently being scrolled towards. This is an observable value and will change as the pager scrolls either by gesture or animation.

Functions

updateCurrentPage

public fun ScrollScope.updateCurrentPage(
        page: Int,
        @FloatRange(from = -0.5, to = 0.5) pageOffsetFraction: Float = 0.0f,
    )

Jump immediately to a given page with a given pageOffsetFraction inside a ScrollScope. Use this method to create custom animated scrolling experiences. This will update the value of currentPage and currentPageOffsetFraction immediately, but can only be used inside a ScrollScope, use scroll to gain access to a ScrollScope.

Please refer to the sample to learn how to use this API.

Parameters

updateTargetPage

public fun ScrollScope.updateTargetPage(targetPage: Int)

Used to update targetPage during a programmatic scroll operation. This can only be called inside a ScrollScope and should be called anytime a custom scroll (through scroll) is executed in order to correctly update targetPage. This will not move the pages and it's still the responsibility of the caller to call ScrollScope.scrollBy in order to actually get to targetPage. By the end of the scroll block, when the GlimmerHorizontalPager is no longer scrolling targetPage will assume the value of currentPage.

Please refer to the sample to learn how to use this API.

requestScrollToPage

public fun requestScrollToPage(
        @IntRange(from = 0) page: Int,
        @FloatRange(from = -0.5, to = 0.5) pageOffsetFraction: Float = 0.0f,
    )

Requests the page to be at the snapped position during the next remeasure, offset by pageOffsetFraction, and schedules a remeasure.

The scroll position will be updated to the requested position rather than maintain the index based on the current page key (when a data set change will also be applied during the next remeasure), but only for the next remeasure.

Any scroll in progress will be cancelled.

Parameters

scrollToPage

public suspend fun scrollToPage(page: Int)

Scroll immediately to the given page, without animating.

Parameters

animateScrollToPage

public suspend fun animateScrollToPage(
        page: Int,
        animationSpec: AnimationSpec<Float> = spring(),
    )

Scroll to the given page with an animation.

Parameters

getOffsetDistanceInPages

public fun getOffsetDistanceInPages(page: Int): Float

A utility function to help to calculate a given page's offset. This is an offset that represents how far page is from the settled position (represented by currentPage offset). The difference here is that currentPageOffsetFraction is a value between -0.5 and 0.5 and the value calculated by this function can be larger than these numbers if page is different than currentPage.

For instance, if currentPage=0 and we call getOffsetDistanceInPages for page 3, the result will be 3, meaning the given page is 3 pages away from the current page (the sign represent the direction of the offset, positive is forward, negative is backwards). Another example is if currentPage=3 and we call getOffsetDistanceInPages for page 1, the result would be -2, meaning we're 2 pages away (moving backwards) to the current page.

This offset also works in conjunction with currentPageOffsetFraction, so if currentPage is out of its snapped position (i.e. currentPageOffsetFraction!=0) then the calculated value will still represent the offset in number of pages (in this case, not whole pages). For instance, if currentPage=1 and we're slightly offset, currentPageOffsetFraction=0.2, if we call this to page 2, the result would be 0.8, that is 0.8 page away from current page (moving forward).

Parameters

Returns

Companion Object

Properties

public val Saver: Saver<GlimmerPagerState, *>

The default Saver implementation for GlimmerPagerState.