Google is committed to advancing racial equity for Black communities. See how.

ScrollOrientationLocker

class ScrollOrientationLocker
kotlin.Any
   ↳ androidx.compose.ui.gesture.scrollorientationlocking.ScrollOrientationLocker

Manages scroll orientation locking amongst all participating gesture filters.

Does so by allowing gesture filters to do the following:

  1. Request that pointers be locked to particular Orientations
  2. Query which pointers from a given set are allowed to be considered for a given orientation.

A specific contract must also be followed in order to setup and tear down scroll orientation locking. Please see onPointerInputSetup, onPointerInputTearDown, onCustomEvent, and onCancel to use this correctly.

Summary

Public constructors
<init>(customEventDispatcher: CustomEventDispatcher)

Manages scroll orientation locking amongst all participating gesture filters.

Public methods
Unit

Locks the PointerIds associated with the changes to orientation.

List<PointerInputChange>

Filters the changes for those that are allowed to be acted upon for the orientation.

Unit

Handles the tear down of internal state due to a call to PointerInputFilter.onCancel.

Unit

Handles the other half of onPointerInputSetup and must be called in all calls to PointerInputFilter.onCustomEvent.

Unit

Handles the initialization of scroll orientation locking management, including internally managed distribution of shared state.

Unit

Handles the tear down of internal state.

Public constructors

<init>

ScrollOrientationLocker(customEventDispatcher: CustomEventDispatcher)

Manages scroll orientation locking amongst all participating gesture filters.

Does so by allowing gesture filters to do the following:

  1. Request that pointers be locked to particular Orientations
  2. Query which pointers from a given set are allowed to be considered for a given orientation.

A specific contract must also be followed in order to setup and tear down scroll orientation locking. Please see onPointerInputSetup, onPointerInputTearDown, onCustomEvent, and onCancel to use this correctly.

Public methods

attemptToLockPointers

fun attemptToLockPointers(
    changes: List<PointerInputChange>,
    orientation: Orientation
): Unit

Locks the PointerIds associated with the changes to orientation.

This effects which changes are returned by getPointersFor.

Pointers that are already locked to a given orientation cannot be later locked to a different orientation.

Exceptions
IllegalStateException if this method is called when this ScrollOrientationLocker has not yet been initialized. This is likely happening because onPointerInputSetup is not being called with every PointerEventPass before this method is being called.

getPointersFor

fun getPointersFor(
    changes: List<PointerInputChange>,
    orientation: Orientation
): List<PointerInputChange>

Filters the changes for those that are allowed to be acted upon for the orientation.

A change can be acted on if it was not already locked in the other orientation.

For example, if pointer 1 was previously locked to Horizontal via attemptToLockPointers then calling this method with pointers 1 and 2 and the following orientation will result in the following pointers being returned:

  • Orientation.Horizontal -> (1, 2)
  • Orientation.Vertical -> (2)
Exceptions
IllegalStateException if this method is called when this ScrollOrientationLocker has not yet been initialized. This is likely happening because onPointerInputSetup is not being called with every PointerEventPass before this method is being called.

onCancel

fun onCancel(): Unit

Handles the tear down of internal state due to a call to PointerInputFilter.onCancel.

Must be called in PointerInputFilter.onCancel.

onCustomEvent

fun onCustomEvent(
    customEvent: CustomEvent,
    pass: PointerEventPass
): Unit

Handles the other half of onPointerInputSetup and must be called in all calls to PointerInputFilter.onCustomEvent.

Exceptions
IllegalStateException if this ScrollOrientationLocker receives a ShareScrollOrientationLockerEvent via this method after having already dispatched a ShareScrollOrientationLockerEvent itself.

onPointerInputSetup

fun onPointerInputSetup(
    changes: List<PointerInputChange>,
    pass: PointerEventPass
): Unit

Handles the initialization of scroll orientation locking management, including internally managed distribution of shared state.

For proper initialization to work, onCustomEvent must also be called in PointerInputFilter.onCustomEvent.

This method should simply be called toward the top of PointerInputFilter.onPointerInput for all PointerEventPasses, before attemptToLockPointers or getPointersFor are called.

onPointerInputTearDown

fun onPointerInputTearDown(
    changes: List<PointerInputChange>,
    pass: PointerEventPass
): Unit

Handles the tear down of internal state.

This method must be called toward the bottom of PointerInputFilter.onPointerInput for all PointerEventPasses, and attemptToLockPointers or getPointersFor should not be called afterwards.