PointHandler QML Type

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

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

속성

• acceptedButtons : flags
• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• cursorShape : Qt::CursorShape
• enabled : bool
• grabPermissions : flags
• margin : real
• parent : Item
• point : handlerPoint
• target : real

신호

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

상세 설명

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

누름 이벤트가 발생하면, 각 PointHandler 인스턴스는 그 순간 아직 “선점”되지 않은 단일 지점을 선택합니다: PointerHandler::parent 의 경계 내에서 누름이 발생하고, 동일한 PointerHandler::parent 내의 형제 PointHandler가 아직 해당 지점에 대해 수동 그랩(passive grab)을 획득하지 않았으며, acceptedButtons, acceptedDevices 등과 같은 다른 제약 조건이 충족된다면, 해당 지점은 적격으로 간주되며 PointHandler는 수동 그랩을 획득합니다. 이러한 방식으로, PointerHandler::parent 는 배타적인 그룹처럼 작동합니다. 즉, PointHandler 인스턴스가 여러 개 존재할 수 있으며, 눌린 터치포인트 집합은 이들 인스턴스들 사이에 분배됩니다. 추적할 점을 선택한 각 PointHandler는 active 속성( true)을 갖게 됩니다. 이후 해당 PointHandler는 릴리스될 때까지 선택한 점을 계속 추적하며, point 의 속성은 최신 상태로 유지됩니다. 모든 Item은 이러한 속성에 바인딩하여 해당 포인트의 움직임을 따라갈 수 있습니다.

단순히 수동적인 그랩퍼 역할을 수행함으로써, 모든 움직임을 독립적으로 감시할 수 있는 능력을 갖습니다. 다른 제스처가 감지되거나 배타적인 그랩이 발생하더라도 이 수동 그랩은 빼앗기거나 재정의될 수 없습니다.

이벤트 포인트에 대한 직교 감시가 목표라면, 이전의 대안으로 ` QObject::installEventFilter()`가 있었지만, 이는 ` QtQuick `의 내장 기능은 아니었습니다. 이 기능을 사용하려면 ` QQuickItem ` 서브클래스와 같은 C++ 코드가 필요합니다. PointHandler는 QQuickWindow 에서 정상적인 이벤트 전달 과정에서 포인터 이벤트만 전달받기 때문에, 이벤트 필터보다 더 효율적입니다. 반면 이벤트 필터는 모든 유형의 QEvent를 모두 필터링해야 하므로, 잠재적인 이벤트 전달 병목 현상이 될 수 있습니다.

한 가지 가능한 사용 사례는 이 핸들러를 ( z 값을 높게 설정하여) 장면의 나머지 요소들 위에 위치한 투명한 Item에 추가하는 것입니다. 이렇게 하면 포인트가 새로 눌렸을 때 해당 Item과 그 핸들러들에게 가장 먼저 이벤트가 전달되어, 수동적인 그랩을 가능한 한 빨리 처리할 수 있는 기회를 제공합니다. 이러한 아이템(예: 전체 UI를 덮고 있는 유리판)은 항상 최상단에 위치해야 하는 반응형 피드백을 시각화하는 다른 아이템들의 편리한 부모가 될 수 있으며, 마찬가지로 팝업, 팝오버, 대화 상자 등의 부모가 될 수도 있습니다. 이러한 방식으로 사용할 경우, main.cpp에서 ` QQmlContext::setContextProperty()`를 사용하여 전체 UI에서 ID를 통해 “유리 패널”에 접근할 수 있도록 하면, 다른 Item 및 PointHandler를 해당 Item으로 부모를 재설정할 수 있어 유용할 수 있습니다.

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
            }
        }
    }
}

모든 입력 핸들러와 마찬가지로, PointHandler에는 target 속성이 있으며, 이 속성은 포인트 추적 Item을 배치하기에 편리한 위치로 사용될 수 있습니다. 하지만 PointHandler는 target 항목을 어떤 방식으로도 자동으로 조작하지 않습니다. point 에 반응하도록 하려면 바인딩을 사용해야 합니다.

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
    }
}

acceptedButtons: \c Qt.NoButton

를 선언하여 이 문제를 방지하는 것이 유용합니다. Qt::AA_SynthesizeMouseForUnhandledTouchEvents 및 Qt::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

이 속성이 설정된 경우, PointHandler 는 PointerEvents 에 반응하기 위해 지정된 키보드 수정 키가 눌려 있어야 하며, 그렇지 않은 경우에는 해당 키들을 무시합니다.

이 속성이 ` 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 조합으로 설정하면, 해당 핸들러를 활성화하려면 모든 수정 키가 눌려야 함을 의미합니다.

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

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

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

enabled : bool

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

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

grabPermissions : flags

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

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

margin : real

parent 항목의 경계를 벗어난 여백으로, 이 범위 내에서 eventPoint 가 이 핸들러를 활성화할 수 있습니다.

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

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

point : handlerPoint [read-only]

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

target : real

조작할 Item을 편리하게 담거나 피드백을 표시할 수 있는 속성입니다. 다른 Pointer Handler와 달리, PointHandler 는 target 에 대해 자체적으로 아무런 작업도 수행하지 않습니다. 일반적으로 SinglePointHandler::point 및 PointHandler::active 와 같은 속성에 대한 반응형 바인딩을 생성해야 합니다. 여기서 Item 인스턴스를 선언하는 경우, PointHandler 는 Item이 아니므로 parent 를 명시적으로 설정해야 합니다.

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

Signal 문서

canceled(eventPoint point)

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

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

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

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

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