TapHandler QML Type

탭 및 클릭 처리기. 더 보기...

• 상속된 멤버를 포함한 모든 멤버 목록

속성

• acceptedButtons : flags
• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• exclusiveSignals : enumeration (since 6.5)
• gesturePolicy : enumeration
• grabPermissions : flags
• longPressThreshold : real
• margin : real
• parent : Item
• point : handlerPoint
• pressed : bool
• tapCount : int
• target : Item
• timeHeld : real

신호

• canceled(eventPoint point)
• doubleTapped(eventPoint eventPoint, Qt::MouseButton button)
• grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
• longPressed()
• singleTapped(eventPoint eventPoint, Qt::MouseButton button)
• tapCountChanged()
• tapped(eventPoint eventPoint, Qt::MouseButton button)

상세 설명

TapHandler는 터치스크린의 탭 또는 마우스 클릭을 처리하는 핸들러입니다.

유효한 탭 제스처의 감지는 ` gesturePolicy`에 따라 결정됩니다. 기본값은 `DragThreshold`이며, 이 경우 누름과 떼기가 공간적·시간적으로 근접해야 합니다. 이 경우, TapHandler는 수동적인 그랩(passive grab)만으로도 작동할 수 있으므로, 다른 Item이나 Input Handler로 전달되는 이벤트를 방해하지 않습니다. 따라서 바인딩 및/또는 JavaScript 콜백을 가진 TapHandler를 추가하여 기존 컨트롤이나 Item의 동작을 수정하고자 할 때 기본 gesturePolicy 가 유용합니다.

단, 버튼(예: QPushButton)은 누름과 떼기가 가까이 발생하든 상관없이 동작하도록 구현되는 경우가 많습니다. 버튼을 눌렀다가 마음을 바꾸면, 클릭을 취소하기 위해 버튼 가장자리 밖으로 완전히 드래그해야 합니다. 이러한 사용 사례에서는 gesturePolicy 을 TapHandler.ReleaseWithinBounds 로 설정하십시오.

import QtQuick

Rectangle {
    id: button
    signal clicked
    property alias text: buttonLabel.text

    height: Math.max(Screen.pixelDensity * 7, buttonLabel.implicitHeight * 1.2)
    width: Math.max(Screen.pixelDensity * 11, buttonLabel.implicitWidth * 1.3)
    radius: 3
    property color dark: Qt.darker(palette.button, 1.3)
    gradient: Gradient {
        GradientStop { position: 0.0; color: tapHandler.pressed ? dark : palette.button }
        GradientStop { position: 1.0; color: dark }
    }

    TapHandler {
        id: tapHandler
        gesturePolicy: TapHandler.ReleaseWithinBounds
        onTapped: button.clicked()
    }

    Text {
        id: buttonLabel
        text: "Click Me"
        color: palette.buttonText
        anchors.centerIn: parent
    }
}

다중 탭 제스처(더블 탭, 트리플 탭 등)의 경우, 이동 거리는 마우스의 경우 QStyleHints::mouseDoubleClickDistance()을, 터치의 경우 QStyleHints::touchDoubleTapDistance()을 초과해서는 안 되며, 탭 사이의 시간 간격은 QStyleHints::mouseDoubleClickInterval()을 초과해서는 안 됩니다.

MouseArea 및 Qt Quick 예제 - 포인터 핸들러도참조하십시오 .

속성 설명서

acceptedButtons : flags

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

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

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

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

acceptedDevices : flags

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

기본적으로 이 속성은 ` PointerDevice.AllDevices`로 설정되어 있습니다. 장치 유형을 OR 연산으로 조합하여 설정하면, 일치하지 않는 장치에서 발생하는 이벤트는 무시됩니다.

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

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

acceptedModifiers : flags

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

이 속성이 ` 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도 참조하십시오 .

acceptedPointerTypes : flags

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

기본적으로 이 속성은 ` 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()
   }
}

active : bool [read-only]

이 메서드는 해당 입력 핸들러가 하나 이상의 이벤트 포인트( eventPoints)에 대한 배타적 확보(exclusive grab)에 성공하여, 해당 포인트들을 처리할 전적인 책임을 맡게 될 때마다 ` true `를 반환합니다. 이는 해당 입력 핸들러가 해당 이벤트 포인트들의 움직임에 따라 자신의 속성을 최신 상태로 유지하고, ` target `(있는 경우)를 능동적으로 조작하고 있음을 의미합니다.

cursorShape : Qt::CursorShape

이 속성은 ‘ 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.SplitV커서
• Qt.SplitHCursor
• Qt.손가락가리키기커서
• Qt.금지 커서
• Qt.이건뭐지커서
• Qt.바쁜 커서
• Qt.열린손 커서
• Qt.주먹 커서
• Qt.드래그복사커서
• Qt.DragMoveCursor
• Qt.DragLinkCursor

기본값이 설정되어 있지 않으므로, parent 항목의 cursor 가 표시됩니다. 이 속성을 undefined로 설정하면 동일한 초기 상태로 재설정할 수 있습니다.

Qt::CursorShape, QQuickItem::cursor(), HoverHandler::cursorShape도 참조하십시오 .

dragThreshold : int

eventPoint 을 드래그 제스처로 인식시키기 위해 사용자가 드래그해야 하는 픽셀 단위 거리입니다.

기본값은 플랫폼과 화면 해상도에 따라 달라집니다. 이 값을 `undefined`로 설정하면 기본값으로 재설정할 수 있습니다. 드래그 제스처가 시작될 때의 동작은 핸들러마다 다릅니다.

enabled : bool

PointerHandler 가 비활성화된 경우, 모든 이벤트를 거부하며 신호가 발신되지 않습니다.

PointerHandler 의 ` parent ` 속성이 ` disabled`로 설정된 경우, ` enabled ` 속성이 ` true`로 유지되더라도 핸들러는 사실상 비활성화됩니다.

exclusiveSignals : enumeration [since 6.5]

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

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

gesturePolicy : enumeration

탭 또는 길게 누르기 제스처가 인식되기 위한 공간적 제약 조건은, 손가락을 떼는 시점이 ` longPressThreshold `가 경과하기 전이어야 한다는 제약 조건 외에도 적용됩니다. 이러한 제약 조건이 충족되지 않으면 ` tapped ` 신호가 발생하지 않으며, ` tapCount `도 증가하지 않습니다. 공간적 제약 조건이 위반될 경우, 누르고 있는 시간과 관계없이 ` pressed `는 즉시 `true`에서 `false`로 전환됩니다.

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 예제 - 포인터 핸들러'에서는 이러한 기능의 몇 가지 사용 사례를 보여줍니다.

grabPermissions : flags

이 속성은 이 핸들러의 로직이 배타적 그랩을 인수하기로 결정하거나, 다른 핸들러로부터 그랩 인수 또는 취소를 승인해 달라는 요청을 받았을 때의 권한을 지정합니다.

기본값은 ` PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything `이며, 이는 대부분의 인수 시나리오를 허용하되, 예를 들어 두 개의 `PinchHandler`가 동일한 터치 포인트를 놓고 충돌하는 상황을 방지합니다.

longPressThreshold : real

eventPoint 가 길게 누르기 제스처를 트리거하고 longPressed() 신호를 발생시키기 위해 눌러져야 하는 시간(초 단위)으로, 이 값이 0 보다 클 경우에 적용됩니다. 이 시간 제한 전에 손가락을 떼면, gesturePolicy 제약 조건이 충족될 경우 탭으로 감지될 수 있습니다. longPressThreshold 가 0 인 경우, 타이머가 비활성화되어 신호가 발생하지 않습니다. longPressThreshold 가 undefined 로 설정된 경우, 대신 기본값이 사용되며 이 속성에서 해당 값을 다시 읽을 수 있습니다.

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

margin : real

parent 항목의 경계 너머에 위치한 여백으로, 이 범위 내에서 eventPoint 가 이 핸들러를 활성화할 수 있습니다. 예를 들어, target 가 parent 이기도 한 PinchHandler 의 경우, 이 값을 일반 사용자의 손가락 너비의 절반 이상으로 설정하는 것이 유용합니다. 이렇게 하면 parent 가 매우 작은 크기로 축소되었을 때도 핀치 제스처를 사용할 수 있기 때문입니다. 또는, 화면 가장자리 근처에 TapHandler 기반 버튼을 배치하면 피츠의 법칙(Fitts’s Law)을 준수하는 데 활용할 수 있습니다. 즉, 버튼이 시각적으로는 가장자리에서 몇 픽셀 떨어져 있어도 화면 가장자리에서의 마우스 클릭에 반응하도록 할 수 있습니다.

기본값은 0입니다.

parent : Item

Item 는 핸들러의 적용 범위이며, 이 핸들러가 선언된 Item입니다. 핸들러는 이 Item을 대신하여 이벤트를 처리하며, 이는 포인터 이벤트의 eventPoints 중 적어도 하나가 Item의 내부에서 발생할 경우 해당 이벤트가 관련이 있음을 의미합니다. 초기에는 target() 가 동일하지만, 재할당될 수 있습니다.

target 및 QObject::parent()도 참조하십시오 .

point : handlerPoint [read-only]

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

pressed : bool [read-only]

마우스나 터치 지점이 눌려 있을 때마다 이 값은 true를 유지하며, 눌린 이후의 모든 움직임은 현재 ‘ gesturePolicy ’에 부합해야 합니다. ‘ eventPoint ’가 해제되거나 정책이 위반되면, ‘pressed’는 false로 변경됩니다.

tapCount : int [read-only]

단일 제스처로 간주되기 위해 시간 및 공간적 제약 조건 내에서 발생한 탭의 횟수입니다. 버튼 상태가 변경되면 카운터는 1로 재설정됩니다. 예를 들어, 트리플 탭을 감지하려면 다음과 같이 작성할 수 있습니다:

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

target : Item

이 핸들러가 조작할 아이템입니다.

기본적으로 이는 ` parent`과 동일하며, 즉 핸들러가 선언된 아이템입니다. 하지만 한 아이템 내에서 이벤트를 처리하면서도 다른 아이템을 조작하거나, ` null`을 통해 기본 동작을 비활성화하고 대신 다른 작업을 수행하기 위해 대상 아이템을 다른 아이템으로 설정하는 것이 유용한 경우도 있습니다.

timeHeld : real [read-only]

드래그 임계값을 초과하지 않은 상태에서 버튼을 누른 채로 유지한 시간(초 단위). 이 값은 렌더링되는 프레임당 최소 한 번씩 업데이트되며, 이를 통해 길게 누를 때 트리거되는 동작으로의 진행 상황을 보여주는 애니메이션을 렌더링할 수 있습니다. 또한, 버튼을 누르고 있는 시간에 따라 일련의 동작 중 하나를 트리거할 수도 있습니다.

값이 0보다 작으면 이 핸들러의 ` Item` 내에 누르고 있는 점이 없음을 의미합니다.

Signal 문서

canceled(eventPoint point)

이 핸들러가 이미 지정된 point 를 확보한 상태라면, 다른 포인터 핸들러나 아이템이 이를 빼앗을 때 이 신호가 발생합니다.

doubleTapped(eventPoint eventPoint, Qt::MouseButton button)

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

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

이 신호는 그랩에 이 핸들러와 관련된 어떤 변화가 발생했을 때 발생합니다.

transition (동사)는 어떤 일이 발생했는지를 나타냅니다. point (목적어)는 잡히거나 풀린 지점입니다.

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

longPressed()

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

singleTapped(eventPoint eventPoint, Qt::MouseButton button)

이 신호는 ‘ parent ’ 항목을 한 번 탭했을 때 발생합니다. ‘ QStyleHints::mouseDoubleClickInterval ’보다 긴 시간이 경과한 후에는 다시 탭할 수 있지만, 다음 탭까지 남은 시간이 이보다 짧을 경우 ‘ tapCount ’ 값이 증가합니다. ‘ eventPoint ’ 신호 매개변수에는 릴리스 이벤트에서 탭된 지점에 대한 정보가 포함되어 있으며, ‘ button ’는 클릭된 ‘ mouse button ’이거나 터치스크린의 경우 ‘ NoButton ’에 해당합니다.

tapCountChanged()

이 신호는 ‘ parent ’ 항목을 한 번 이상 탭했을 때(지정된 시간 및 거리 범위 내에서) 그리고 현재 tapCount 가 이전 tapCount 와 다를 때 발생합니다.

tapped(eventPoint eventPoint, Qt::MouseButton button)

이 신호는 ‘ 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)
    }
}