WheelHandler QML Type

마우스 휠 핸들러. 더 보기...

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

속성

• acceptedDevices : flags
• acceptedModifiers : flags
• active : bool
• activeTimeout : real
• blocking : bool (since 6.3)
• enabled : bool
• invertible : bool
• margin : real
• orientation : enumeration
• parent : Item
• point : handlerPoint
• property : string
• rotation : real
• rotationScale : real
• target : Item
• targetScaleMultiplier : real
• targetTransformAroundCursor : bool

신호

• wheel(WheelEvent event)

상세 설명

WheelHandler는 사용자가 마우스 휠을 회전할 때 아이템의 특정 수치 속성을 대화형으로 조작하는 데 사용되는 핸들러입니다. 다른 입력 핸들러와 마찬가지로, 기본적으로 이 핸들러는 대상 속성( target)을 조작합니다. 조작할 대상 속성을 제어하려면 ` property `를 선언하십시오:

import QtQuick

Rectangle {
    width: 170; height: 120
    color: "green"; antialiasing: true

    WheelHandler {
        property: "rotation"
        onWheel: (event)=> console.log("rotation", event.angleDelta.y,
                                       "scaled", rotation, "@", point.position,
                                       "=>", parent.rotation)
    }
}

BoundaryRule 는 WheelHandler(및 다른 입력 핸들러)와 함께 사용하여 대상 속성이 가질 수 있는 허용 값 범위를 선언하는 데 매우 유용합니다. 예를 들어, WheelHandler와 DragHandler 를 조합하여 사용자가 마우스 휠을 돌리거나 터치스크린에서 항목을 드래그할 때 스크롤 가능한 항목의 y 속성을 조작하고, BoundaryRule 를 사용하여 상단에서 하단까지의 이동 범위를 제한함으로써 스크롤 기능을 구현할 수 있습니다:

import QtQuick
import Qt.labs.animation

Item {
    width: 320; height: 480
    Flow {
        id: content
        width: parent.width
        spacing: 2; padding: 2

        WheelHandler {
            orientation: Qt.Vertical
            property: "y"
            rotationScale: 15
            acceptedDevices: PointerDevice.Mouse | PointerDevice.TouchPad
            onActiveChanged: if (!active) ybr.returnToBounds()
        }

        DragHandler {
            xAxis.enabled: false
            onActiveChanged: if (!active) ybr.returnToBounds()
        }

        BoundaryRule on y {
            id: ybr
            minimum: content.parent.height - content.height
            maximum: 0
            minimumOvershoot: 400; maximumOvershoot: 400
            overshootFilter: BoundaryRule.Peak
        }

        Repeater {
            model: 1000
            Rectangle { color: "gray"; width: 10 + Math.random() * 100; height: 15 }
        }
    }
}

반면, property 이 설정되지 않았거나 target 이 null인 경우, WheelHandler는 자동으로 어떤 조작도 수행하지 않습니다. 하지만 rotation 속성을 바인딩에 사용하여 다른 속성을 조작하거나, onWheel 를 구현하여 휠 이벤트를 직접 처리할 수 있습니다.

WheelHandler는 기본적으로 회전하는 마우스 휠만 처리합니다. 이는 acceptedDevices 를 설정하여 변경할 수 있습니다.

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

속성 설명서

acceptedDevices : flags

이 핸들러를 실행할 수 있는 포인팅 장치의 유형입니다.

기본적으로 이 속성은 PointerDevice.Mouse 로 설정되어 있어, 실제 마우스 휠에서 발생하는 이벤트에만 반응하도록 되어 있습니다.

WheelHandler acceptedDevices를 ` PointerDevice.Mouse | PointerDevice.TouchPad`로 설정하면 마우스 휠과 터치패드 스크롤링 모두에 반응하도록 할 수 있습니다.

acceptedModifiers : flags

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

이 속성이 ` Qt.KeyboardModifierMask `(기본값)로 설정된 경우, ` WheelHandler `는 수정 키를 무시합니다.

예를 들어, ` Item `에는 두 개의 핸들러가 있을 수 있는데, 그중 하나는 필요한 키보드 수정 키가 눌렸을 때만 활성화되고, 다른 하나는 수정 키가 눌려 있으면 이벤트를 무시합니다:

import QtQuick

Rectangle {
    width: 170; height: 120
    color: "green"; antialiasing: true

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

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

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

Qt::KeyboardModifier도 참조하십시오 .

active : bool [read-only]

WheelHandler 가 최근에 QWheelEvent 를 확인했고, 속성을 최신 상태로 유지하고 있으며, target (있는 경우)를 적극적으로 조작하고 있는 경우, true 가 성립합니다.

activeTimeout도 참조하십시오 .

activeTimeout : real

더 이상 휠 이벤트가 수신되지 않을 경우, ` active ` 속성이 ` false `으로 되돌아가기까지 걸리는 시간(초 단위). 기본값은 ` 0.1 `(100 ms)입니다.

WheelHandler 가 일부 터치패드에서 발생하는 이벤트와 같이 ' scroll phase ' 정보를 포함하는 이벤트를 처리할 경우, 'phase' 속성이 ' Qt::ScrollEnd '인 이벤트가 수신되는 즉시 ' active ' 속성은 ' false '로 변경되며, 이 경우 타임아웃은 필요하지 않습니다. 그러나 휠이 있는 일반 마우스는 스크롤 단계를 제공하지 않습니다. 마우스는 사용자가 스크롤을 중지하기로 결정한 시점을 감지할 수 없기 때문에, active 속성은 지정된 시간이 경과한 후 false 로 전환됩니다.

QWheelEvent::phase()도 참조하십시오 .

blocking : bool [since 6.3]

이 핸들러가 그 뒤에 있는 다른 항목이나 핸들러가 동일한 휠 이벤트를 처리하는 것을 차단하는지 여부입니다. 이 속성의 기본값은 ` true `입니다.

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

enabled : bool

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

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

invertible : bool

QWheelEvent::inverted 가 true 일 때 속성 변경 방향을 반전할지 여부입니다. 기본값은 true 입니다.

운영 체제에 손가락 움직임과 동일한 방향으로 스크롤되도록 하는 “자연 스크롤(natural scrolling)” 설정이 있는 경우, 이 속성이 ` true`로 설정되어 있고 ` WheelHandler `가 ` target`에 속성을 직접 설정하는 경우, 이동 방향은 시스템 설정에 따라 결정됩니다. 이 속성이 false 로 설정된 경우, rotation 를 반전시켜 이동 방향이 항상 손가락 움직임의 방향과 동일하게 됩니다.

margin : real

parent 항목의 경계 너머에 있는 여백으로, WheelHandler 가 반응할 수 있는 영역입니다. 예를 들어, margin 가 10 로 설정되어 있다면, 항목의 보이는 가장자리에서 최대 10픽셀 바깥쪽에 커서를 두더라도 휠에 반응합니다:

import QtQuick

Rectangle {
    width: 170; height: 120
    color: "green"; antialiasing: true

    WheelHandler {
        property: "rotation"
        margin: 10
    }
}

기본값은 0 입니다.

orientation : enumeration

어떤 휠에 반응할지. 기본값은 Qt.Vertical 입니다.

모든 마우스에 Horizontal 휠이 있는 것은 아니며, 때로는 휠을 옆으로 기울여 이 기능을 에뮬레이션하기도 합니다. 터치패드는 일반적으로 수직 및 수평 휠 이벤트를 모두 생성할 수 있습니다.

parent : Item

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

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

point : handlerPoint [read-only]

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

property : string

마우스 휠을 돌렸을 때 ` target `에서 수정될 속성입니다.

기본값은 속성이 없음(빈 문자열)입니다. 자동으로 수정되는 대상 속성이 없는 경우, 바인딩을 사용하여 마우스 휠 회전에 임의의 방식으로 반응할 수 있습니다.

마우스 휠을 사용하여 모든 숫자형 속성을 조정할 수 있습니다. 예를 들어, ` property `가 ` x`로 설정된 경우, 휠을 돌리면 ` target `가 수평으로 이동합니다. 다음 속성들은 특별한 동작을 보입니다:

지정된 대상 속성의 조정 값은 항상 rotationScale 에 따라 스케일링됩니다.

rotation : real

이 속성이 마지막으로 설정된 이후 마우스 휠이 회전된 각도로, 휠 각도로 표시됩니다.

양수 값은 휠이 위쪽/오른쪽으로 회전했음을 나타내고, 음수 값은 휠이 아래쪽/왼쪽으로 회전했음을 나타냅니다.

기본 마우스 휠은 15도 단위로 작동합니다.

시작 시 기본값은 0 입니다. 이 값은 프로그래밍을 통해 언제든지 원하는 값으로 설정할 수 있습니다. 사용자가 마우스 휠을 회전함에 따라 이 값은 그에 따라 조정됩니다.

orientation도 참조하십시오 .

rotationScale : real

rotation 속성과, 해당 target 항목에 설정된 property (있는 경우)에 적용될 배율입니다. 기본값은 1이며, 이 경우 rotation 는 회전 각도 단위로 표시됩니다. 마우스 휠 회전 방향의 효과를 반전시키려면 음수 값으로 설정할 수 있습니다.

target : Item

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

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

targetScaleMultiplier : real

rotation 가 15도 변할 때마다 target scale 에 곱해질 값입니다. 이는 property 가 "scale" 일 때만 적용됩니다.

scale 는 targetScaleMultiplier ^{angleDelta * rotationScale / 15를} 곱하게 됩니다. 기본값은 2 ^1/3이며, 이는 rotationScale 를 기본값으로 두고 마우스 휠을 한 번 “클릭”(15도) 돌릴 경우, target 의 크기가 약 1.25배로 조정됨을 의미합니다. 휠을 세 번 “클릭”하면 휠이 회전된 방향에 따라 크기가 두 배가 되거나 절반으로 줄어듭니다. 휠을 두 번 클릭할 때마다 크기를 두 배로 늘리거나 절반으로 줄이고 싶다면, 이 값을 2 ^1/2 (1.4142)로 설정하십시오. 휠을 돌리는 방향과 반대 방향으로 크기가 조정되도록 하려면, ‘ rotationScale ’를 음수 값으로 설정하십시오.

targetTransformAroundCursor : bool

property 을 조정하는 동안 target 이 마우스 커서 위치를 중심으로 변환되도록 자동으로 위치를 재조정해야 하는지 여부입니다. 기본값은 ‘ true ’입니다.

property 가 "rotation" 로 설정되어 있고 targetTransformAroundCursor가 true 인 경우, 휠을 돌리면 target 항목이 마우스 커서 위치를 중심으로 제자리에서 회전합니다. targetTransformAroundCursor 가 false 인 경우, 대신 transformOrigin 을 중심으로 회전합니다.

Signal 문서

wheel(WheelEvent event)

이 핸들러가 QWheelEvent 타입의 event 를 수신할 때마다, 즉 휠이 움직이거나 스크롤 제스처가 업데이트될 때마다 이 신호가 발생합니다.