PointHandler QML Type

단일 터치포인트에 반응하기 위한 핸들러입니다. 더 보기...

Import Statement: import QtQuick
Inherits:

SinglePointHandler

속성

신호

  • canceled(eventPoint point)
  • grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

상세 설명

PointHandler는 터치포인트나 마우스 위치에 대한 피드백을 표시하거나 포인터 이벤트에 반응하는 데 사용할 수 있습니다.

누르기 이벤트가 발생하면 PointHandler의 각 인스턴스는 그 순간에 아직 "잡히지 않은" 단일 포인트를 선택합니다: PointerHandler::parent 의 범위 내에서 누름이 발생하고 동일한 PointerHandler::parent 내에 아직 해당 포인트에 대한 패시브 그랩을 획득한 형제 PointHandler가 없고 acceptedButtons, acceptedDevices 등과 같은 다른 제약 조건이 충족되면 해당 포인트가 적격하며, 그 다음 PointHandler가 패시브 그랩을 획득합니다. 이런 식으로 PointerHandler::parent 은 독점적인 그룹처럼 작동합니다. 여러 개의 포인트 핸들러 인스턴스가 있을 수 있으며, 누른 터치포인트 세트는 이들 사이에 분산됩니다. 추적할 지점을 선택한 각 포인트핸들러는 active 속성 true 을 갖습니다. 그런 다음 릴리스될 때까지 선택한 지점을 계속 추적하며 point 의 프로퍼티는 최신 상태로 유지됩니다. 모든 아이템은 이러한 프로퍼티에 바인딩하여 포인트의 움직임을 따라갈 수 있습니다.

패시브 그래버일 뿐이므로 모든 움직임을 독립적으로 감독할 수 있습니다. 다른 제스처가 감지되어 독점적인 그랩이 발생하더라도 패시브 그랩은 도용되거나 재정의될 수 없습니다.

이벤트포인트의 직교 감시가 목표인 경우 이전에는 QObject::installEventFilter()를 사용했지만, 이는 QtQuick 기능에 내장된 것이 아니라 QQuickItem 서브클래스와 같은 일부 C++ 코드가 필요합니다. 이벤트 필터는 모든 유형의 모든 QEvent를 필터링해야 하므로 잠재적인 이벤트 전달 병목 현상이 발생할 수 있는 반면, PointHandler는 QQuickWindow 에서 일반적인 이벤트 전달 과정에서 포인터 이벤트만 전달하므로 이보다 더 효율적입니다.

한 가지 가능한 사용 사례는 이 핸들러를 장면의 나머지 부분 위에 있는 투명한 아이템에 추가하여( z 값이 높으면) 포인트를 새로 누르면 해당 아이템과 해당 핸들러에 먼저 전달되어 가능한 한 빨리 패시브 잡기를 할 수 있는 기회를 제공하는 것입니다. 이러한 항목(전체 UI의 유리창과 같은)은 항상 상단에 있어야 하는 반응형 피드백을 시각화하는 다른 항목의 편리한 부모가 될 수 있으며, 마찬가지로 팝업, 팝오버, 대화 상자 등의 부모가 될 수 있습니다. 이런 식으로 사용할 경우, main.cpp에서 QQmlContext::setContextProperty()를 사용하여 전체 UI에서 ID로 액세스할 수 있는 '유리창'을 만들어 다른 항목과 포인트 핸들러가 다시 부모가 될 수 있도록 하는 것이 도움이 될 수 있습니다.

import QtQuick

Window {
    width: 480
    height: 320
    visible: true

    Item {
        id: glassPane
        z: 10000
        anchors.fill: parent

        PointHandler {
            id: handler
            acceptedDevices: PointerDevice.TouchScreen | PointerDevice.TouchPad
            target: Rectangle {
                parent: glassPane
                color: "red"
                visible: handler.active
                x: handler.point.position.x - width / 2
                y: handler.point.position.y - height / 2
                width: 20; height: width; radius: width / 2
            }
        }
    }
}

모든 입력 핸들러와 마찬가지로 포인트 핸들러에는 target 프로퍼티가 있어 포인트 추적 아이템을 넣는 편리한 장소로 사용할 수 있지만, 포인트 핸들러는 target 항목을 어떤 식으로든 자동으로 조작하지는 않습니다. 바인딩을 사용하여 point 에 반응하도록 해야 합니다.

참고: macOS에서 PointHandler는 기본적으로 트랙패드의 여러 손가락에 반응하지 않지만, 눌린 지점(마우스 위치)에는 반응합니다. 이는 macOS가 기본 제스처 인식 또는 원시 터치포인트 중 하나를 제공할 수 있지만 둘 다 제공하지는 않기 때문입니다. 저희는 PinchHandler 에서 네이티브 제스처 이벤트를 사용하는 것을 선호하므로 터치를 활성화하여 비활성화하지 않으려 합니다. 그러나 MultiPointTouchArea 은 터치를 활성화하여 전체 창에서 기본 제스처 인식을 비활성화하므로 모든 터치포인트에만 반응하고 부드러운 기본 제스처 환경이 필요하지 않은 경우 대안이 될 수 있습니다.

MultiPointTouchArea, HoverHandler, Qt Quick 예제 - 포인터 핸들러를참조하세요 .

속성 문서

acceptedButtons : flags

이를 활성화할 수 있는 마우스 버튼 PointHandler.

기본적으로 이 속성은 Qt.LeftButton 으로 설정되어 있습니다. 마우스 버튼의 OR 조합으로 설정할 수 있으며 다른 버튼을 누르거나 누르고 있는 이벤트를 무시합니다. Qt.NoButton 으로 설정된 경우 버튼은 전혀 신경 쓰지 않으며, 이미 진짜 eventPoint 을 처리하고 있는 모든 장치에서 발생하는 합성 마우스 이벤트를 무시한다는 의미입니다.

import QtQuick

Item {
    width: 480; height: 320

    Rectangle {
        color: handler.active ? "tomato" : "wheat"
        x: handler.point.position.x - width / 2
        y: handler.point.position.y - height / 2
        width: 20; height: width; radius: width / 2
    }

    PointHandler {
        id: handler
        acceptedButtons: Qt.MiddleButton | Qt.RightButton
    }
}

참고: 터치스크린에는 버튼이 없으므로 이 속성은 PointHandler 이 터치포인트에 반응하는 것을 방지하지 않습니다.

참고: 기본적으로 이 속성이 Qt.LeftButton 를 보유할 때 마우스가 아닌 PointerDevice (예: 터치스크린 또는 그래픽 태블릿 스타일러스)가 합성 마우스 이벤트를 생성하도록 허용되면 일반적으로 마우스 왼쪽 버튼이 눌렸음을 나타내며 이러한 이벤트는 장치에서 이미 진짜 eventPoint 에 반응하고 있던 PointHandler 을 일시적으로 비활성화할 수 있습니다. 이 문제를 방지하려면

acceptedButtons: \c Qt.NoButton

를 선언하는 것이 유용합니다. Qt::AA_SynthesizeMouseForUnhandledTouchEventsQt::AA_SynthesizeMouseForUnhandledTabletEvents 을 참조하세요.


acceptedDevices : flags

PointHandler 을 활성화할 수 있는 포인팅 디바이스 유형.

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

PointHandler {
    id: handler
    acceptedDevices: PointerDevice.TouchScreen | PointerDevice.TouchPad
    target: Rectangle {
        parent: glassPane
        color: "red"
        visible: handler.active
        x: handler.point.position.x - width / 2
        y: handler.point.position.y - height / 2
        width: 20; height: width; radius: width / 2
    }
}

acceptedModifiers : flags

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

이 속성이 Qt.KeyboardModifierMask (기본값)로 설정된 경우 PointHandler 은 수정자 키를 무시합니다.

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

import QtQuick

Item {
    id: feedbackPane
    width: 480; height: 320

    PointHandler {
        id: control
        acceptedModifiers: Qt.ControlModifier
        cursorShape: Qt.PointingHandCursor
        target: Rectangle {
            parent: feedbackPane
            color: control.active ? "indianred" : "khaki"
            x: control.point.position.x - width / 2
            y: control.point.position.y - height / 2
            width: 20; height: width; radius: width / 2
        }
    }

    PointHandler {
        id: shift
        acceptedModifiers: Qt.ShiftModifier | Qt.MetaModifier
        cursorShape: Qt.CrossCursor
        target: Rectangle {
            parent: feedbackPane
            color: shift.active ? "darkslateblue" : "lightseagreen"
            x: shift.point.position.x - width / 2
            y: shift.point.position.y - height / 2
            width: 30; height: width; radius: width / 2
        }
    }
}

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

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

상수설명
NoModifier수정자 키는 허용되지 않습니다.
ShiftModifier키보드의 Shift 키를 눌러야 합니다.
ControlModifier키보드의 Ctrl 키를 눌러야 합니다.
AltModifier키보드의 Alt 키를 눌러야 합니다.
MetaModifier키보드의 메타 키를 눌러야 합니다.
KeypadModifier키패드 버튼을 눌러야 합니다.
GroupSwitchModifierX11 전용(Windows에서 명령줄 인수로 활성화하지 않은 경우). 키보드의 Mode_switch 키를 눌러야 합니다.
KeyboardModifierMask핸들러는 어떤 수정자를 눌렀는지는 신경 쓰지 않습니다.

Qt::KeyboardModifier참조하세요 .


acceptedPointerTypes : flags

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

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

import QtQuick

Canvas {
    id: canvas
    width: 800
    height: 600
    antialiasing: true
    renderTarget: Canvas.FramebufferObject
    property var points: []
    onPaint: {
        if (points.length < 2)
            return
        var ctx = canvas.getContext('2d');
        ctx.save()
        ctx.strokeStyle = stylusHandler.active ? "blue" : "white"
        ctx.lineCap = "round"
        ctx.beginPath()
        ctx.moveTo(points[0].x, points[0].y)
        for (var i = 1; i < points.length; i++)
            ctx.lineTo(points[i].x, points[i].y)
        ctx.lineWidth = 3
        ctx.stroke()
        points = points.slice(points.length - 2, 1)
        ctx.restore()
    }

    PointHandler {
        id: stylusHandler
        acceptedPointerTypes: PointerDevice.Pen
        onPointChanged: {
            canvas.points.push(point.position)
            canvas.requestPaint()
        }
    }

    PointHandler {
        id: eraserHandler
        acceptedPointerTypes: PointerDevice.Eraser
        onPointChanged: {
            canvas.points.push(point.position)
            canvas.requestPaint()
        }
    }

    Rectangle {
        width: 10; height: 10
        color: stylusHandler.active ? "green" : eraserHandler.active ? "red" : "beige"
    }
}

Qt Quick 예제 - 포인터 핸들러에는 그래픽 태블릿으로 캔버스에 그리는 좀 더 복잡한 예제가 포함되어 있습니다.


active : bool [read-only]

제약 조건이 충족될 때마다 true 을 유지하고 PointHandler 이 반응합니다. 즉, 제약 조건을 만족하는 eventPoints 의 움직임에 따라 프로퍼티를 최신 상태로 유지합니다.


cursorShape : Qt::CursorShape

이 속성은 activetrue 인 동안 마우스가 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 가 표시됩니다. 이 속성을 정의되지 않음으로 설정하여 동일한 초기 조건으로 재설정할 수 있습니다.

참고: 이 속성이 설정되지 않았거나 undefined 로 설정된 경우 값을 읽으면 Qt.ArrowCursor 이 반환됩니다.

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


enabled : bool

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


grabPermissions : flags

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

Constant설명
PointerHandler.TakeOverForbidden이 핸들러는 어떤 유형의 아이템이나 핸들러로부터도 그랩 권한을 받거나 주지 않습니다.
PointerHandler.CanTakeOverFromHandlersOfSameType이 핸들러는 같은 클래스의 다른 핸들러로부터 독점적인 그랩을 받을 수 있습니다.
PointerHandler.CanTakeOverFromHandlersOfDifferentType이 핸들러는 모든 종류의 핸들러로부터 독점 그래브를 가져올 수 있습니다.
PointerHandler.CanTakeOverFromItems이 핸들러는 모든 유형의 아이템에서 독점 그래브를 가져올 수 있습니다.
PointerHandler.CanTakeOverFromAnything이 핸들러는 모든 유형의 아이템 또는 핸들러로부터 독점 그래브를 가져올 수 있습니다.
PointerHandler.ApprovesTakeOverByHandlersOfSameType이 핸들러는 같은 클래스의 다른 핸들러가 그랩을 가져갈 수 있는 권한을 부여합니다.
PointerHandler.ApprovesTakeOverByHandlersOfDifferentType이 핸들러는 모든 종류의 핸들러가 그랩을 가져갈 수 있는 권한을 부여합니다.
PointerHandler.ApprovesTakeOverByItems이 핸들러는 모든 종류의 아이템에 그랩을 할 수 있는 권한을 부여합니다.
PointerHandler.ApprovesCancellation이 핸들러는 해당 핸들러의 그랩을 null로 설정할 수 있습니다.
PointerHandler.ApprovesTakeOverByAnything이 핸들러는 모든 유형의 아이템 또는 핸들러가 그랩을 가져갈 수 있는 권한을 부여합니다.

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


margin : real

eventPoint 이 이 핸들러를 활성화할 수 있는 parent 항목의 범위를 벗어나는 여백입니다.

기본값은 0 입니다.

import QtQuick

Item {
    width: 480; height: 320

    Rectangle {
        anchors.fill: handlingContainer
        anchors.margins: -handler.margin
        color: "beige"
    }

    Rectangle {
        id: handlingContainer
        width: 200; height: 200
        anchors.centerIn: parent
        border.color: "green"
        color: handler.active ? "lightsteelblue" : "khaki"

        Text {
            text: "X"
            x: handler.point.position.x - width / 2
            y: handler.point.position.y - height / 2
            visible: handler.active
        }

        PointHandler {
            id: handler
            margin: 30
        }
    }

}

parent : Item

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

targetQObject::parent()도 참조하세요 .


point : handlerPoint [read-only]

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


target : real

조작할 아이템을 편리하게 보관하거나 피드백을 표시할 수 있는 프로퍼티입니다. 다른 포인터 핸들러와 달리 PointHandlertarget 자체로는 아무것도 하지 않습니다: 보통 SinglePointHandler::pointPointHandler::active 와 같은 프로퍼티에 반응형 바인딩을 만들어야 합니다. 여기서 Item 인스턴스를 선언하는 경우 PointHandler 는 Item이 아니므로 parent 를 명시적으로 설정해야 합니다.

기본적으로 핸들러가 선언된 Item은 parent 과 동일합니다.


신호 문서

canceled(eventPoint point)

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

참고: 해당 핸들러는 onCanceled 입니다.


grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

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

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

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

상수설명
PointerDevice.GrabExclusive이 핸들러는 point 을 처리하는 일차적 책임을 맡았습니다.
PointerDevice.UngrabExclusive이 핸들러가 이전 독점 그래브를 포기했습니다.
PointerDevice.CancelGrabExclusive이 핸들러의 독점 그래브가 인수되었거나 취소되었습니다.
PointerDevice.GrabPassive이 처리기가 point 을 모니터링하기 위해 패시브 그랩을 획득했습니다.
PointerDevice.UngrabPassive이 핸들러가 이전 패시브 그랩을 포기했습니다.
PointerDevice.CancelGrabPassive이 처리기의 이전 패시브 그랩이 비정상적으로 종료되었습니다.

참고: 해당 핸들러는 onGrabChanged 입니다.


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.