PinchHandler QML Type

핀치 제스처 핸들러. 더 보기...

• 상속된 멤버를 포함한 모든 멤버 목록
• 사용 중단된 멤버

속성

• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• activeRotation : real
• activeScale : real
• activeTranslation : point
• centroid : QtQuick::handlerPoint
• cursorShape : Qt::CursorShape
• dragThreshold : int
• enabled : bool
• grabPermissions : flags
• margin : real
• parent : Item
• persistentRotation : real
• persistentScale : real
• persistentTranslation : point
• rotationAxis
  • rotationAxis.activeValue : real
  • rotationAxis.enabled : bool
  • rotationAxis.maximum : real
  • rotationAxis.minimum : real
• scaleAxis
  • scaleAxis.activeValue : real
  • scaleAxis.enabled : bool
  • scaleAxis.maximum : real
  • scaleAxis.minimum : real
• target : Item
• xAxis
  • xAxis.activeValue : real
  • xAxis.enabled : bool
  • xAxis.maximum : real
  • xAxis.minimum : real
• yAxis
  • yAxis.activeValue : real
  • yAxis.enabled : bool
  • yAxis.maximum : real
  • yAxis.minimum : real

신호

• canceled(eventPoint point)
• grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
• rotationChanged(qreal delta)
• scaleChanged(qreal delta)
• translationChanged(QVector2D delta)

상세 설명

PinchHandler는 다중 손가락 제스처를 해석하여 항목을 대화식으로 회전, 확대/축소 및 드래그하는 핸들러입니다. 다른 입력 핸들러와 마찬가지로, 기본적으로 모든 기능을 갖추고 있으며, 선언된 항목인 ` target`을 조작합니다.

import QtQuick

Rectangle {
    width: 400
    height: 300
    color: "lightsteelblue"
    PinchHandler { }
}

이 핸들러에는 드래그, 회전 및 확대/축소 범위를 제한하는 속성이 있습니다.

하나의 Item 내에서 선언되었지만 다른 target 가 할당된 경우, 외부 Item의 경계 내에서 이벤트를 처리하지만 대신 target Item을 조작합니다:

import QtQuick

Item {
    width: 640
    height: 480

    Rectangle {
        id: map
        color: "aqua"
        width: 400
        height: 300
    }

    PinchHandler {
        target: map
    }
}

세 번째 사용 방법은 ` target `을 ` null `로 설정하고, 속성 변경에 대해 다른 방식으로 반응하는 것입니다:

import QtQuick

Window {
    width: 320; height: 240
    visible: true
    title: handler.persistentRotation.toFixed(1) + "° " +
           handler.persistentTranslation.x.toFixed(1) + ", " +
           handler.persistentTranslation.y.toFixed(1) + " " +
           (handler.persistentScale * 100).toFixed(1) + "%"

    PinchHandler {
        id: handler
        target: null
        persistentScale: 0.25
        onTranslationChanged: (delta) => {
            image.x -= delta.x
            image.y -= delta.y
        }
    }

    Image {
        id: image
        source: "images/album-cover.jpg"
        scale: handler.persistentScale
        x: -600; y: -450
    }
}

PinchArea, QPointerEvent::pointCount(), QNativeGestureEvent::fingerCount(), Qt Quick 및 '예제 - 포인터 핸들러'항목도 참조하십시오 .

속성 문서

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]

이 속성은 모든 제약 조건(특히 minimumPointCount 및 maximumPointCount)이 충족되고, 만약 target 가 존재한다면 해당 속성이 조작되고 있을 때 true 입니다.

activeRotation : real [read-only]

핀치 제스처의 회전 각도(도)로, 양의 값은 시계 방향을 나타냅니다. 제스처가 시작될 때 이 값은 ` 0 `입니다. ` target `가 null이 아닐 경우, 이 값은 자동으로 ` rotation`에 추가됩니다. 그렇지 않은 경우, 바인딩을 사용하여 이 값으로 임의의 작업을 수행할 수 있습니다.

QtQuick::PinchHandler::rotationAxis.activeValue도 참조하십시오 .

activeScale : real [read-only]

핀치 제스처가 수행되는 동안의 배율 계수입니다. 제스처가 시작될 때는 1.0이며, 터치 지점이 멀어지면 증가하고, 터치 지점이 가까워지면 감소합니다. ` target `가 null이 아닌 경우, 해당 ` scale ` 값에 이 값이 자동으로 곱해집니다. 그렇지 않은 경우, 바인딩을 사용하여 이 값으로 임의의 작업을 수행할 수 있습니다.

QtQuick::PinchHandler::scaleAxis.activeValue도 참조하십시오 .

activeTranslation : point [read-only]

핀치 제스처가 수행되는 동안 점 클러스터의 변위량입니다. 제스처가 시작될 때는 0, 0 이며, eventPoint(s) 를 아래쪽 및 오른쪽 방향으로 드래그할수록 증가합니다. 제스처가 종료된 후에는 변위량이 그대로 유지되며, 다음 핀치 제스처가 시작되면 다시 0, 0 로 재설정됩니다.

centroid : QtQuick::handlerPoint [read-only]

현재 선택된 터치 지점들의 정확히 중앙에 위치한 점입니다. ‘ 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`로 유지되더라도 핸들러는 사실상 비활성화됩니다.

grabPermissions : flags

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

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

margin : real

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

기본값은 0입니다.

parent : Item

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

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

persistentRotation : real

target 가 null이 아닌 경우 적용될 회전값입니다. 그렇지 않은 경우, 바인딩을 사용하여 이 값으로 임의의 작업을 수행할 수 있습니다. 핀치 제스처가 수행되는 동안 activeRotation 가 지속적으로 추가되며, 제스처가 종료된 후에는 값이 그대로 유지되고, 다음 핀치 제스처가 시작되면 activeRotation 에 의해 다시 수정되기 시작합니다.

이 속성을 설정하여, 예를 들어 다른 핸들러를 통해 설정된 회전과 기준 회전을 동기화할 수 있습니다. 이 속성을 직접 설정하더라도 activeRotation 는 변경되지 않으며, rotationChanged(0) 이 발생합니다.

persistentScale : real

target 가 null이 아닐 경우 자동으로 설정되는 배율 계수입니다. 그렇지 않은 경우, 바인딩을 사용하여 이 값을 통해 임의의 작업을 수행할 수 있습니다. 핀치 제스처가 수행되는 동안 이 값은 activeScale 로 지속적으로 곱해지며, 제스처가 종료된 후에는 동일한 값을 유지합니다. 다음 핀치 제스처가 시작되면 다시 activeScale 로 곱해지기 시작합니다.

이 속성을 설정하면, 예를 들어 다른 핸들러를 통해 설정된 스케일과 기본 스케일을 동기화할 수 있습니다. 이 속성을 직접 설정하더라도 activeScale 는 변경되지 않으며, scaleChanged(1) 가 발생합니다.

persistentTranslation : point

target 에 적용될 변환 값으로, 해당 값이 ` null`가 아닐 경우에만 사용됩니다. 그렇지 않은 경우, 바인딩을 사용하여 이 값으로 임의의 작업을 수행할 수 있습니다. 핀치 제스처가 수행되는 동안 ` activeTranslation `가 지속적으로 값에 더해지며, 제스처가 종료된 후에는 값이 그대로 유지됩니다.

이 속성을 설정하여, 다른 핸들러를 통해 설정된 변위와 같은 방식으로 기준 변위를 동기화할 수 있습니다. 이 속성을 직접 설정하더라도 activeTranslation 는 변경되지 않으며, translationChanged({0, 0}) 가 발생합니다.

rotationAxis group

rotationAxis 터치포인트 그룹의 회전 각도에 따라 ‘ target ’ 항목의 ‘ rotation ’을 설정하는 제약 조건을 제어합니다.

minimum 는 허용되는 최소 회전 각도입니다. maximum 는 허용되는 최대 회전 각도입니다. enabled 가 true인 경우 회전이 허용됩니다. activeValue 는 QtQuick::PinchHandler::activeRotation 와 동일합니다.

` activeValueChanged ` 신호는 ` activeValue `가 변경될 때 발생하며, 변경된 증분 값을 제공합니다. 이는 여러 핸들러를 통해 하나의 속성을 점진적으로 조정하기 위한 것입니다.

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"; antialiasing: true

    PinchHandler {
        id: handler
        target: null
        xAxis.onActiveValueChanged: (delta) => parent.radius -= delta
        yAxis.onActiveValueChanged: (delta) => parent.border.width += delta
        rotationAxis.onActiveValueChanged: (delta) => parent.rotation += delta // add
        scaleAxis.onActiveValueChanged: (delta) => parent.scale *= delta // multiply
    }

    WheelHandler {
        acceptedModifiers: Qt.NoModifier
        property: "rotation"
    }

    WheelHandler {
        acceptedModifiers: Qt.ControlModifier
        property: "scale"
    }
}

scaleAxis group

scaleAxis 터치포인트 간의 거리에 따라 ‘ target ’ 항목의 ‘ scale ’을 설정하는 제약 조건을 제어합니다.

minimum 는 허용되는 최소 배율입니다. maximum 는 허용되는 최대 배율입니다. enabled 가 true인 경우, 배율 조정이 허용됩니다. activeValue 는 QtQuick::PinchHandler::activeScale 과 동일합니다.

activeValueChanged 신호는 activeValue 가 변경될 때 발생하며, 증분 변경에 대한 배율을 제공합니다. 이는 여러 핸들러를 통해 하나의 속성을 점진적으로 조정하기 위한 것입니다.

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"; antialiasing: true

    PinchHandler {
        id: handler
        target: null
        xAxis.onActiveValueChanged: (delta) => parent.radius -= delta
        yAxis.onActiveValueChanged: (delta) => parent.border.width += delta
        rotationAxis.onActiveValueChanged: (delta) => parent.rotation += delta // add
        scaleAxis.onActiveValueChanged: (delta) => parent.scale *= delta // multiply
    }

    WheelHandler {
        acceptedModifiers: Qt.NoModifier
        property: "rotation"
    }

    WheelHandler {
        acceptedModifiers: Qt.ControlModifier
        property: "scale"
    }
}

target : Item

이 핸들러가 조작할 항목입니다.

기본적으로 이는 ` parent`, 즉 핸들러가 선언된 `Item`과 동일합니다. 그러나 한 `Item` 내에서 이벤트를 처리하되 다른 `Item`을 조작하기 위해, 또는 ` null`하여 기본 동작을 비활성화하고 대신 다른 작업을 수행하기 위해 대상을 다른 `Item`으로 설정하는 것이 유용한 경우가 있습니다.

xAxis group

xAxis target 항목의 수평 이동에 대한 제약 조건을 제어합니다.

minimum 는 이동 시 허용되는 최소 x 좌표입니다. maximum 는 이동 시 허용되는 최대 x 좌표입니다. enabled 가 true인 경우, 수평 드래그가 허용됩니다.

` activeValue `가 변경되면 ` activeValueChanged ` 신호가 발생하여 변경된 증가량을 제공합니다. 이는 여러 핸들러를 통해 하나의 속성을 점진적으로 조정하기 위한 것입니다.

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"; antialiasing: true

    PinchHandler {
        id: handler
        target: null
        xAxis.onActiveValueChanged: (delta) => parent.radius -= delta
        yAxis.onActiveValueChanged: (delta) => parent.border.width += delta
        rotationAxis.onActiveValueChanged: (delta) => parent.rotation += delta // add
        scaleAxis.onActiveValueChanged: (delta) => parent.scale *= delta // multiply
    }

    WheelHandler {
        acceptedModifiers: Qt.NoModifier
        property: "rotation"
    }

    WheelHandler {
        acceptedModifiers: Qt.ControlModifier
        property: "scale"
    }
}

yAxis group

yAxis target 항목의 수직 이동에 대한 제약 조건을 제어합니다.

minimum 는 변환 시 허용되는 최소 y 좌표입니다. maximum 는 변환 시 허용되는 최대 y 좌표입니다. enabled 가 true인 경우, 수직 드래그가 허용됩니다.

` activeValue `가 변경되면 ` activeValueChanged ` 신호가 발생하여 변경된 증분 값을 제공합니다. 이는 여러 핸들러를 통해 하나의 속성을 점진적으로 조정하기 위한 것입니다.

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"; antialiasing: true

    PinchHandler {
        id: handler
        target: null
        xAxis.onActiveValueChanged: (delta) => parent.radius -= delta
        yAxis.onActiveValueChanged: (delta) => parent.border.width += delta
        rotationAxis.onActiveValueChanged: (delta) => parent.rotation += delta // add
        scaleAxis.onActiveValueChanged: (delta) => parent.scale *= delta // multiply
    }

    WheelHandler {
        acceptedModifiers: Qt.NoModifier
        property: "rotation"
    }

    WheelHandler {
        acceptedModifiers: Qt.ControlModifier
        property: "scale"
    }
}

Signal 문서

canceled(eventPoint point)

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

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

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

transition (동사)는 어떤 일이 발생했는지를 나타냅니다. point (목적어)는 그랩되었거나 그랩이 해제된 지점을 나타냅니다.

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

rotationChanged(qreal delta)

` rotationChanged ` 신호는 ` activeRotation `(따라서 ` persistentRotation`)가 변경될 때 발생합니다. ` delta ` 값은 회전의 가산적 변화를 나타냅니다. 예를 들어, 사용자가 손가락을 움직여 핀치 거리를 변경하여 ` activeRotation `가 10도에서 30도로 바뀌면, ` rotationChanged(20) `가 발생합니다. 이를 활용하여 항목의 회전을 점진적으로 변경할 수 있습니다:

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"

    PinchHandler {
        id: handler
        target: null
        onRotationChanged: (delta) => parent.rotation += delta // add
        onScaleChanged: (delta) => parent.scale *= delta // multiply
    }
}

scaleChanged(qreal delta)

` scaleChanged ` 신호는 ` activeScale `(따라서 ` persistentScale`)가 변경될 때 발생합니다. ` delta ` 값은 배율의 배수적 변화를 나타냅니다. 예를 들어, 사용자가 손가락을 움직여 핀치 거리를 변경하여 ` activeScale `가 2에서 2.5로 바뀌면 ` scaleChanged(1.25) `가 발생합니다. 이를 활용하여 항목의 배율을 점진적으로 변경할 수 있습니다:

import QtQuick

Rectangle {
    width: 100; height: 100
    color: "lightsteelblue"

    PinchHandler {
        id: handler
        target: null
        onRotationChanged: (delta) => parent.rotation += delta // add
        onScaleChanged: (delta) => parent.scale *= delta // multiply
    }
}

translationChanged(QVector2D delta)

` translationChanged ` 신호는 ` activeTranslation `(따라서 ` persistentTranslation`)이 변경될 때 발생합니다. ` delta ` 벡터는 평행 이동의 변화를 나타냅니다. 이를 사용하여 항목의 위치를 점진적으로 변경할 수 있습니다:

import QtQuick

Window {
    width: 320; height: 240
    visible: true
    title: handler.persistentRotation.toFixed(1) + "° " +
           handler.persistentTranslation.x.toFixed(1) + ", " +
           handler.persistentTranslation.y.toFixed(1) + " " +
           (handler.persistentScale * 100).toFixed(1) + "%"

    PinchHandler {
        id: handler
        target: null
        persistentScale: 0.25
        onTranslationChanged: (delta) => {
            image.x -= delta.x
            image.y -= delta.y
        }
    }

    Image {
        id: image
        source: "images/album-cover.jpg"
        scale: handler.persistentScale
        x: -600; y: -450
    }
}