AwaitPointerEventScope

@RestrictsSuspension
@JvmDefaultWithCompatibility /* = JvmDefaultWithCompatibility */
public interface AwaitPointerEventScope
    : Density

터치 이벤트를 비동기적으로 기다리는 데 사용되는 스코프. 사용자가 터치 입력을 수행하는 동안 발생하는 여러 이벤트를 처리하는 데 필요한 기능 제공
주로 Modifier.pointerInput와 함께 사용

주요 기능

비동기 이벤트 대기

• 특정 터치 이벤트(터치, 드래그 등) 대기
  이벤트 수집
• 사용자가 터치를 시작하면 해당 이벤트를 수집하고, 여러 이벤트(드래그, 탭, 롱 프레스 등)를 처리할 수 있다
  상태 관리
• 이벤트를 처리하는 동안 상태를 관리할 수 있으며, 이를 통해 UI 상호작용 구현

멤버 변수

val size: IntSize
- 주로 UI 요소의 크기를 나타냄. 터치 이벤트가 발생할 수 있는 영역의 크기 제공
val extendedTouchPadding: Size
- 터치 영역을 확장하기 위한 추가적인 패딩 영역
val currentEvent: PointerEvent
- 현재 처리되고 있는 포인터 이벤트(탭, 드래그 등)에 대한 정보를 제공
val viewConfiguration: ViewConfiguration
- 터치 민감도, 스크롤 속도 등에 대한 정보

멤버 함수

awaitPointerEvent: 현재 coroutine scope안에서 새로운 포언티 이벤트가 발생할 때까지 일시 정지되며 이벤트가 발생하면 반환.

public abstract suspend fun awaitPointerEvent(
    pass: PointerEventPass = PointerEventPass.Main
): PointerEvent

withTimeout(withTimeoutOrNull): timeMillis이 초과하면 TimeoutCancellationException(null)을 발생시키는 함수

public open suspend fun <T> withTimeout(
    timeMillis: Long,
    block: suspend AwaitPointerEventScope.() -> T
): T

주요 확장 함수

awaitFirstDown: 사용자가 처음 화면을 터치했을 때의 이벤트를 대기

• 사용자가 화면을 터치하기 전까지는 실행되지 않고 대기하는 메서드

public suspend fun AwaitPointerEventScope.awaitFirstDown(
    requireUnconsumed: Boolean = true,
    pass: PointerEventPass = PointerEventPass.Main
): PointerInputChange

horizontalDrag : 터치한 id에 해당하는 아이템이 수평으로 드래그될 때의 이벤트를 처리

suspend fun AwaitPointerEventScope.horizontalDrag(
    pointerId: PointerId,
    onDrag: (PointerInputChange) -> Unit
): Boolean = drag(
    pointerId = pointerId,
    onDrag = onDrag,
    orientation = Orientation.Horizontal,
    motionConsumed = { it.isConsumed }
) != null

LazyStaggeredGridScope

LazyStaggeredGridScope

sealed interface LazyStaggeredGridScope {
    fun item(
        key: Any? = null,
        contentType: Any? = null,
        span: StaggeredGridItemSpan? = null,
        content: @Composable LazyStaggeredGridItemScope.() -> Unit
    )
      
    fun items(
        count: Int,
        key: ((index: Int) -> Any)? = null,
        contentType: (index: Int) -> Any? = { null },
        span: ((index: Int) -> StaggeredGridItemSpan)? = null,
        itemContent: @Composable LazyStaggeredGridItemScope.(index: Int) -> Unit
    )

item 함수는 Lazy Staggered Grid에 단일 아이템을 추가합니다.
key (default : 항목의 위치가 키)

• item을 나타내는 고유한 키
• 키는 Android에서 Bundle을 통해 저장할 수 있어야 한다.
• 스태거드 그리드의 여러 항목에 대해 동일한 키를 사용할 수 없고 이는 LazyStaggedGridState.requestScrollToItem을 호출하여 재정의할 수 있다
• 키를 지정하면 Lazy Staggered Grid는 해당 키를 가진 아이템이 사용자가 가장 먼저 볼 수 있도록 스크롤 위치를 조정하려고 한다. 이는 데이터의 추가나 제거가 발생해도 사용자 경험을 유지할 수 있는 중요한 메커니즘이다

contentType (default : 모든 item은 어떤 유형에도 속하게 간주)

• 아이템의 콘텐츠 유형을 나타내는 파라미터
• 동일 유형의 아이템 콘텐츠는 더 효율적으로 재사용될 수 있다.
• contentType을 설정함으로써 Lazy Staggered Grid는 각 아이템의 유형에 따라 적절한 레이아웃을 계산하고, 필요한 경우에만 아이템을 생성하거나 재사용하여 성능을 최적화

span(default : itme이 하나의 레인을 사용)

• StaggedGridCells에서 정의한 레인 수를 구성
• StaggeredGridItemSpan.FullLine과 StaggeredGridItemSpan.SingleLane을 사용

class StaggeredGridItemSpan private constructor(internal val value: Int) {
    companion object {
        // 가로축 전체 사용
        val FullLine = StaggeredGridItemSpan(0)
        
        // 지정된 column의 길이 전체 사용
        val SingleLane = StaggeredGridItemSpan(1)
    }
}

content

• 아이템의 내용을 결정하는 람다식 @Composable 함수를 통해 아이템의 UI를 정의

PointerInputScope

@JvmDefaultWithCompatibility
interface PointerInputScope : Density

터치 및 포인터 입력을 처리. 해당 스코프는 포인터 입력을 수신하고, 해당 입력에 대한 반응을 정의하는데 필요한 여러기능과 도구를 포함
Modifier.pointerInput 수정자의 스코프

coroutine scope에서 동작

• coroutine scope에서 독장하며, suspend fun 을 사용하여 비동기적으로 이벤트를 처리
  포인터 이벤트 처리
• 터치, 마우스 클릭, 드래그 등의 포인터 입력 이벤트를 수신하고 처리하는 데 사용
  포인터 입력 대기
• awaitPointerEventScope 함수를 사용하여 특정 포인터 이벤트 대기

멤버 변수

val size: IntSize

• 포인터 입력 크기 ex) Button이 있다면 해당 버튼을 누를 수 있는 범위
  val extendedTouchPadding: Size
• 실제 UI 요소에 추가되는 포인터 입력 범위
  val viewConfiguration: ViewConfiguration
• 현재 장치의 터치 입력관련 설정을 제공(민감도, 최대 스크롤 속도, 터치 간격 등)
  var interceptOutOfBoundsChildEvents: Boolean
• 부모가 자식의 터치 이벤트를 가로챌 수 있는지 여부
• 스크롤 가능한 목록이나 제스터를 사용할 때 유용

멤버 함수

awaitPointerEventScope : 발생하는 포인터 이벤트를 해당 스코프안에서 처리

suspend fun <R> awaitPointerEventScope(
   block: suspend AwaitPointerEventScope.() -> R
): R

확장 함수

detectTapGestures

• 사용자가 화면을 눌렀을 때의 다양한 제스처(던알 탭, 더블 탭, 롱 프레스 등)를 감지하며 각 제스처에 대해 콜백 함수를 제공
• detectTapAndPress도 있음

public suspend fun PointerInputScope.detectTapGestures(
    onDoubleTap: ((Offset) -> Unit)? = null,
    onLongPress: ((Offset) -> Unit)? = null,
    onPress: suspend PressGestureScope.(Offset) -> Unit = NoPressGesture,
    onTap: ((Offset) -> Unit)? = null
): Unit

detectDragGestures: 드래그 제스처를 감지하고, 각각의 이벤트 처리

public suspend fun PointerInputScope.detectDragGestures(
    onDragStart: (Offset) -> Unit = { },
    onDragEnd: () -> Unit = { },
    onDragCancel: () -> Unit = { },
    onDrag: (change: PointerInputChange, dragAmount: Offset) -> Unit
): Unit

등등