TapHandler QML Type

이 포인터 핸들러를 활성화할 수 있는 마우스 버튼입니다.

기본적으로 이 속성은 Qt.LeftButton 로 설정되어 있습니다. 마우스 버튼의 OR 조합으로 설정할 수 있으며 다른 버튼의 이벤트는 무시합니다.

예를 들어 두 개의 핸들러를 사용하여 왼쪽 및 오른쪽 클릭에 서로 다른 방식으로 반응하도록 컨트롤을 만들 수 있습니다:

Item {
    TapHandler {
        onTapped: console.log("left clicked")
    }
    TapHandler {
        acceptedButtons: Qt.RightButton
        onTapped: console.log("right clicked")
    }
}

이 포인터 핸들러를 활성화할 수 있는 포인팅 장치의 유형입니다.

기본적으로 이 속성은 PointerDevice.AllDevices 로 설정되어 있습니다. 장치 유형의 OR 조합으로 설정하면 일치하지 않는 장치의 이벤트는 무시됩니다.

예를 들어, 두 개의 핸들러를 사용하여 마우스 및 스타일러스 클릭에는 한 가지 방식으로, 터치스크린 탭에는 다른 방식으로 반응하도록 컨트롤을 만들 수 있습니다:

Item {
   TapHandler {
       acceptedDevices: PointerDevice.Mouse | PointerDevice.TouchPad | PointerDevice.Stylus
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedDevices: PointerDevice.TouchScreen
       onTapped: console.log("tapped")
   }
}

이 속성을 설정하면 포인터 이벤트에 반응하기 위해 지정된 키보드 수정자를 눌러야 하며, 그렇지 않으면 무시합니다.

이 속성이 Qt.KeyboardModifierMask (기본값)로 설정되어 있으면 PointerHandler 은 수정자 키를 무시합니다.

예를 들어 Item 에는 같은 유형의 핸들러가 두 개 있을 수 있으며, 이 중 하나는 필요한 키보드 수정자가 눌려야만 활성화됩니다:

Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier
       onTapped: console.log("control-tapped")
   }
   TapHandler {
       acceptedModifiers: Qt.NoModifier
       onTapped: console.log("tapped")
   }
}

acceptedModifiers 을 수정자 키의 OR 조합으로 설정하면 해당 수정자를 모두 눌러야 핸들러를 활성화할 수 있습니다:

Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier | Qt.AltModifier | Qt.ShiftModifier
       onTapped: console.log("control-alt-shift-tapped")
   }
}

사용 가능한 수정자는 다음과 같습니다:

여러 핸들러와 여러 수정자 플래그를 조합하여 달성할 수 있는 것보다 훨씬 더 복잡한 동작이 필요한 경우 JavaScript 코드에서 수정자를 확인할 수 있습니다:

Item {
    TapHandler {
        onTapped:
            switch (point.modifiers) {
            case Qt.ControlModifier | Qt.AltModifier:
                console.log("CTRL+ALT");
                break;
            case Qt.ControlModifier | Qt.AltModifier | Qt.MetaModifier:
                console.log("CTRL+META+ALT");
                break;
            default:
                console.log("other modifiers", point.modifiers);
                break;
            }
    }
}

Qt::KeyboardModifier 를참조하세요 .

이 포인터 핸들러를 활성화할 수 있는 포인팅 도구(손가락, 스타일러스, 지우개 등)의 유형입니다.

기본적으로 이 속성은 PointerDevice.AllPointerTypes 로 설정되어 있습니다. 장치 유형의 OR 조합으로 설정하면 일치하지 않는 devices 의 이벤트는 무시됩니다.

예를 들어 마우스, 터치, 스타일러스 클릭에 어떤 식으로든 반응하지만 그래픽 태블릿에서 지우개 도구로 탭하면 스스로 삭제되도록 컨트롤을 만들 수 있습니다:

Rectangle {
   id: rect
   TapHandler {
       acceptedPointerTypes: PointerDevice.Generic | PointerDevice.Finger | PointerDevice.Pen
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedPointerTypes: PointerDevice.Eraser
       onTapped: rect.destroy()
   }
}

이 입력 핸들러가 하나 이상의 eventPoints 을 단독으로 처리할 때마다 true 을 유지하여 해당 포인트를 독점적으로 잡는 데 성공합니다. 즉, 해당 이벤트포인트의 움직임에 따라 프로퍼티를 최신 상태로 유지하고 target (있는 경우)를 적극적으로 조작합니다.

이 속성은 active 이 true 인 동안 마우스가 parent 항목 위로 마우스를 가져갈 때마다 표시되는 커서 모양을 유지합니다.

사용 가능한 커서 모양은 다음과 같습니다:

• Qt.ArrowCursor
• Qt.UpArrowCursor
• Qt.CrossCursor
• Qt.WaitCursor
• Qt.IBeamCursor
• Qt.SizeVerCursor
• Qt.SizeHorCursor
• Qt.SizeBDiagCursor
• Qt.SizeFDiagCursor
• Qt.SizeAllCursor
• Qt.BlankCursor
• Qt.SplitVCursor
• Qt.SplitHCursor
• Qt.PointingHandCursor
• Qt.ForbiddenCursor
• Qt.WhatsThisCursor
• Qt.BusyCursor
• Qt.OpenHandCursor
• Qt.ClosedHandCursor
• Qt.DragCopyCursor
• Qt.DragMoveCursor
• Qt.DragLinkCursor

기본값은 설정되어 있지 않아 parent 항목의 cursor 가 표시됩니다. 이 속성을 정의되지 않음으로 설정하여 동일한 초기 조건으로 재설정할 수 있습니다.

Qt::CursorShape, QQuickItem::cursor() 및 HoverHandler::cursorShape 를참조하세요 .

드래그 제스처로 처리하기 위해 사용자가 eventPoint 를 드래그해야 하는 픽셀 단위의 거리입니다.

기본값은 플랫폼 및 화면 해상도에 따라 다릅니다. 정의되지 않음으로 설정하면 기본값으로 다시 초기화할 수 있습니다. 드래그 제스처가 시작될 때의 동작은 핸들러마다 다릅니다.

PointerHandler 이 비활성화되면 모든 이벤트를 거부하고 신호를 보내지 않습니다.

singleTapped() 및 doubleTapped() 신호의 독점성을 결정합니다.

이 속성은 Qt 6.5에 도입되었습니다.

탭 또는 길게 누르기 제스처가 인식되기 위한 공간적 제약 조건과 longPressThreshold 이 경과하기 전에 릴리스가 발생해야 한다는 제약 조건이 추가되었습니다. 이러한 제약 조건이 충족되지 않으면 tapped 신호가 전송되지 않고 tapCount 이 증가하지 않습니다. 공간 제약 조건이 위반되면 pressed 은 보유 시간에 관계없이 즉시 참에서 거짓으로 전환됩니다.

gesturePolicy 는 아래 설명된 대로 그랩 동작에도 영향을 줍니다.

Item {
    width: 120; height: 80

    component Button : Rectangle {
        TapHandler {
            id: tapHandler
            gesturePolicy: TapHandler.DragThreshold // the default
            onTapped: tapFlash.start()
        }
    }

    Button { x: 10; y: 10 }
    Button { x: 30; y: 30 }
}

TapHandler {
    id: tapHandler
    gesturePolicy: TapHandler.WithinBounds
    onTapped: tapFlash.start()
}

TapHandler {
    id: tapHandler
    gesturePolicy: TapHandler.ReleaseWithinBounds
    onTapped: tapFlash.start()
}

TapHandler {
    id: menuPopupHandler
    gesturePolicy: TapHandler.DragWithinBounds
    onPressedChanged:
        if (pressed) {
            menu.x = point.position.x - menu.width / 2
            menu.y = point.position.y - menu.height / 2
        } else {
            feedback.text = menu.highlightedMenuItem
            selectFlash.start()
        }
    onCanceled: feedback.text = "canceled"
}

Qt Quick 예제 - 포인터 핸들러는 이에 대한 몇 가지 사용 사례를 보여줍니다.

이 속성은 이 핸들러의 로직이 독점 그랩을 인수하기로 결정할 때 또는 다른 핸들러가 그랩 인수 또는 취소를 승인하도록 요청할 때 권한을 지정합니다.

기본값은 PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything 으로 대부분의 탈취 시나리오를 허용하지만 두 개의 핀치 핸들러가 같은 터치포인트를 놓고 싸우는 것을 방지합니다.

값이 0 보다 클 경우 길게 누르기 제스처를 트리거하고 longPressed() 신호를 내보내기 위해 eventPoint 을 눌러야 하는 시간(초)입니다. 이 시간 제한 전에 포인트를 놓으면 gesturePolicy 제약 조건이 충족되면 탭을 감지할 수 있습니다. longPressThreshold 이 0 인 경우 타이머가 비활성화되고 신호가 방출되지 않습니다. longPressThreshold 이 undefined 으로 설정된 경우 기본값이 대신 사용되며 이 속성에서 다시 읽을 수 있습니다.

기본값은 QStyleHints::mousePressAndHoldInterval()를 초로 변환한 값입니다.

eventPoint 이 핸들러를 활성화할 수 있는 parent 항목의 범위를 벗어나는 여백입니다. 예를 들어 target 이 parent 인 PinchHandler 에서 이 값을 일반적인 사용자 손가락 너비의 절반 이상으로 설정하면 parent 이 매우 작은 크기로 축소된 경우에도 핀치 제스처가 가능합니다. 또는 TapHandler 기반 버튼이 화면 가장자리 근처에 배치된 경우 피츠의 법칙에 따라 버튼이 시각적으로 가장자리에서 몇 픽셀 떨어져 있어도 화면 가장자리에서 마우스 클릭에 반응할 수 있습니다.

기본값은 0입니다.

핸들러의 범위인 Item, 핸들러가 선언된 항목입니다. 핸들러는 이 아이템을 대신하여 이벤트를 처리하므로, eventPoints 중 하나 이상이 아이템 내부에서 발생하면 포인터 이벤트가 관련성이 있다는 뜻입니다. 처음에 target() 은 동일하지만 재할당할 수 있습니다.

target 및 QObject::parent()도 참조하세요 .

현재 처리 중인 eventPoint. 현재 처리 중인 점이 없으면 이 객체는 기본값으로 재설정됩니다(모든 좌표는 0).

마우스 또는 터치 포인트를 누를 때마다 참이 유지되며, 누른 이후의 모든 움직임은 현재 gesturePolicy 을 준수합니다. eventPoint 에서 손을 떼거나 정책을 위반하면 눌렀음은 거짓으로 변경됩니다.

시간 및 공간 제약 조건 내에서 발생한 탭 횟수를 하나의 제스처로 간주합니다. 버튼이 변경되면 카운터는 1로 초기화됩니다. 예를 들어, 세 번 탭을 감지하려면 다음과 같이 작성할 수 있습니다:

Rectangle {
    width: 100; height: 30
    signal tripleTap
    TapHandler {
        acceptedButtons: Qt.AllButtons
        onTapped: if (tapCount == 3) tripleTap()
    }
}

이 핸들러가 조작할 항목.

기본적으로 핸들러가 선언된 항목인 parent 과 동일합니다. 그러나 한 항목 내에서 이벤트를 처리하지만 다른 항목을 조작하기 위해 대상을 다른 항목으로 설정하거나, 기본 동작을 비활성화하고 대신 다른 작업을 수행하려면 null 로 설정하는 것이 유용할 수 있습니다.

드래그 임계값을 초과하여 이동하지 않고 누른 지점이 유지된 시간(초)입니다. 렌더링되는 프레임당 최소 한 번씩 업데이트되므로 길게 누르면 트리거되는 동작의 진행 상황을 보여주는 애니메이션을 렌더링할 수 있습니다. 또한 누르고 있는 시간에 따라 일련의 동작 중 하나를 트리거할 수도 있습니다.

값이 0보다 작으면 이 핸들러의 Item 내에 포인트가 유지되고 있지 않음을 의미합니다.

이 핸들러가 이미 지정된 point 을 잡았다면, 다른 포인터 핸들러나 아이템에 의해 잡힌 경우 이 신호가 발생합니다.

이 신호는 parent 아이템이 짧은 시간(QStyleHints::mouseDoubleClickInterval()) 및 거리(QStyleHints::mouseDoubleClickDistance() 또는 QStyleHints::touchDoubleTapDistance()) 내에 두 번 탭될 때 발생합니다. 이 신호는 항상 singleTapped, tapped, tapCountChanged 다음에 발생합니다. eventPoint 신호 매개변수에는 탭한 지점에 대한 릴리스 이벤트의 정보가 포함되며, button 은 클릭한 mouse button 또는 터치스크린의 경우 NoButton 입니다.

이 신호는 이 핸들러와 관련된 방식으로 그랩이 변경되었을 때 발생합니다.

transition (동사)는 무슨 일이 일어났는지 알려줍니다. point (객체)는 잡히거나 잡히지 않은 지점입니다.

유효한 transition 값은 다음과 같습니다:

이 신호는 parent 항목을 longPressThreshold 보다 큰 시간 동안 길게 누르고 있을 때 발생합니다. 즉, 터치포인트 또는 버튼을 길게 누르고 있는 동안 움직임이 드래그 임계값을 초과하지 않으면 longPressed 신호는 timeHeld 이 longPressThreshold 을 초과하는 시점에 발생합니다.

이 신호는 parent 항목을 한 번 탭할 때 발생합니다. QStyleHints::mouseDoubleClickInterval 보다 큰 시간이 지난 후 다시 탭할 수 있지만 다음 탭까지 시간이 짧으면 tapCount 이 증가합니다. eventPoint 신호 매개변수에는 탭한 지점에 대한 릴리스 이벤트의 정보가 포함되며, button 은 클릭한 mouse button 또는 터치스크린의 경우 NoButton 입니다.

이 신호는 parent 항목이 지정된 시간 및 거리 범위 내에서 한 번 이상 탭되고 현재 tapCount 가 이전 tapCount 과 다를 때 발생합니다.

이 신호는 parent 항목을 탭할 때마다 발산됩니다.

즉, 드래그 임계값을 초과하지 않는 동안 longPressThreshold 보다 짧은 시간 내에 터치포인트 또는 버튼을 눌렀다가 놓으면 tapped 신호가 해제 시점에 발생합니다. eventPoint 신호 매개변수에는 탭한 지점에 대한 릴리스 이벤트의 정보가 포함되어 있으며, button 은 클릭한 mouse button 또는 터치스크린의 경우 NoButton 입니다.

import QtQuick

Rectangle {
    width: 100
    height: 100

    TapHandler {
        acceptedButtons: Qt.LeftButton | Qt.RightButton
        onTapped: (eventPoint, button)=> console.log("tapped", eventPoint.device.name,
                                             "button", button,
                                             "@", eventPoint.scenePosition)
    }
}