MouseArea QML Type

간단한 마우스 조작을 지원합니다. 더 보기...

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

속성

• acceptedButtons : Qt::MouseButtons
• containsMouse : bool
• containsPress : bool
• cursorShape : Qt::CursorShape
• drag
  • drag.active : bool
  • drag.axis : enumeration
  • drag.filterChildren : bool
  • drag.maximumX : real
  • drag.maximumY : real
  • drag.minimumX : real
  • drag.minimumY : real
  • drag.smoothed : bool
  • drag.target : Item
  • drag.threshold : real
• enabled : bool
• hoverEnabled : bool
• mouseX : real
• mouseY : real
• pressAndHoldInterval : int
• pressed : bool
• pressedButtons : MouseButtons
• preventStealing : bool
• propagateComposedEvents : bool
• scrollGestureEnabled : bool

신호

• canceled()
• clicked(MouseEvent mouse)
• doubleClicked(MouseEvent mouse)
• entered()
• exited()
• positionChanged(MouseEvent mouse)
• pressAndHold(MouseEvent mouse)
• pressed(MouseEvent mouse)
• released(MouseEvent mouse)
• wheel(WheelEvent wheel)

상세 설명

MouseArea는 일반적으로 표시되는 항목과 함께 사용되어 해당 항목에 대한 마우스 처리를 제공하는 보이지 않는 항목입니다. 효과적으로 프록시 역할을 수행함으로써, 마우스 처리 로직을 MouseArea 항목 내에 포함시킬 수 있습니다.

enabled 속성은 프록시된 항목에 대한 마우스 처리를 활성화하거나 비활성화하는 데 사용됩니다. 비활성화되면 마우스 영역은 마우스 이벤트에 대해 투명해집니다.

MouseArea는 보이지 않는 Item이지만, visible 속성을 가지고 있습니다. 이 속성을 false로 설정하면 마우스 영역이 마우스 이벤트에 대해 투명해집니다.

pressed 읽기 전용 속성은 사용자가 마우스 영역 위에서 마우스 버튼을 누르고 있는지 여부를 나타냅니다. 이 속성은 사용자 인터페이스 내 속성 간의 바인딩에서 자주 사용됩니다. containsMouse 읽기 전용 속성은 마우스 영역 위에 마우스 커서가 있는지 여부를 나타내지만, 기본적으로 마우스 버튼을 누르고 있을 때만 적용됩니다. 자세한 내용은 containsMouse 문서를 참조하십시오.

마우스 위치 및 버튼 클릭에 대한 정보는 이벤트 핸들러 속성이 정의된 신호를 통해 제공됩니다. 가장 일반적으로 사용되는 것은 마우스 누름 및 클릭 처리를 다루는 onClicked, onDoubleClicked, onPressed, onReleased 및 onPressAndHold입니다. 또한 onWheel 신호를 통해 마우스 휠 이벤트를 처리할 수도 있습니다.

MouseArea가 다른 MouseArea 항목의 영역과 겹치는 경우, ` propagateComposedEvents `를 `true`로 설정하고 전파되어야 할 이벤트를 거부함으로써 ` clicked`, ` doubleClicked ` 및 ` pressAndHold ` 이벤트를 다른 항목으로 전파하도록 선택할 수 있습니다. 자세한 내용은 propagateComposedEvents 문서를 참조하십시오.

기본적으로 MouseArea 항목은 마우스 클릭만 보고하며 마우스 커서 위치의 변경 사항은 보고하지 않습니다. hoverEnabled 속성을 설정하면 마우스 버튼이 눌려 있지 않은 경우에도 onPositionChanged, onEntered 및 onExited에 정의된 핸들러가 사용되고 containsMouse 속성이 업데이트되도록 보장합니다.

사용 예

다음 예제는 클릭 시 ` Rectangle `의 색상을 빨간색으로 변경하는 ` Rectangle ` 내에서 `MouseArea`를 사용하는 예입니다:

import QtQuick

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

    MouseArea {
        anchors.fill: parent
        onClicked: { parent.color = 'red' }
    }
}

많은 MouseArea 신호는 위치, 버튼, 키 수정자 등 마우스 이벤트에 대한 추가 정보가 포함된 mouse 매개변수를 전달합니다.

다음은 영역을 마우스 오른쪽 버튼으로 클릭했을 때 다른 색상을 표시하도록 이전 예제를 확장한 것입니다:

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

    MouseArea {
        anchors.fill: parent
        acceptedButtons: Qt.LeftButton | Qt.RightButton
        onClicked: (mouse)=> {
            if (mouse.button == Qt.RightButton)
                parent.color = 'blue';
            else
                parent.color = 'red';
        }
    }
}

MouseEvent, MouseArea 예제, 그리고 ‘ Qt Quick - 사용자 입력’의 ‘중요한 개념’항목도 참조하십시오 .

속성 설명서

acceptedButtons : Qt::MouseButtons

이 속성은 마우스 영역이 반응하는 마우스 버튼을 지정합니다.

MouseArea 가 여러 개의 버튼에 반응하도록 지정하려면, Qt::MouseButtons 플래그 값을 "|" (또는) 연산자를 사용하여 결합합니다:

MouseArea { acceptedButtons: Qt.LeftButton | Qt.RightButton }

사용 가능한 모든 마우스 버튼을 허용하도록 지정하려면 특수 값 'Qt.AllButtons'를 사용할 수 있습니다:

MouseArea { acceptedButtons: Qt.AllButtons }

기본값은 ` Qt.LeftButton`입니다.

containsMouse : bool [read-only]

이 속성은 마우스가 현재 마우스 영역 내에 있는지 여부를 나타냅니다.

containsPress : bool [read-only]

이는 ` pressed && containsMouse`과 동등한 편의 속성으로, 즉 ` acceptedButtons ` 중 어느 키라도 현재 눌려 있고 마우스가 ` MouseArea` 내에 있는 경우 이 속성이 참이 됩니다.

이 속성은 마우스가 항목의 경계 내에서 눌려 있는 동안 해당 항목을 강조 표시하는 데 특히 유용합니다.

pressed 및 containsMouse도 참조하십시오 .

cursorShape : Qt::CursorShape

이 속성은 해당 마우스 영역의 커서 모양을 지정합니다. 마우스 커서가 표시되지 않는 플랫폼에서는 이 속성이 아무런 효과를 나타내지 않을 수 있습니다.

사용 가능한 커서 모양은 다음과 같습니다:

• 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.OpenHandCursor
• Qt.주먹커서
• Qt.드래그복사커서
• Qt.DragMoveCursor
• Qt.DragLinkCursor

마우스 이벤트에 반응하지 않고 특정 영역에 마우스 커서 모양만 설정하려면 ` acceptedButtons `을 `none`으로 설정하십시오:

MouseArea { cursorShape: Qt.IBeamCursor; acceptedButtons: Qt.NoButton }

기본값은 ` Qt.ArrowCursor`입니다.

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

drag group

drag 항목을 드래그할 수 있게 하는 편리한 방법을 제공합니다.

• drag.target 드래그할 항목의 ID를 지정합니다.
• drag.active 대상 항목이 현재 드래그 중인지 여부를 지정합니다.
• drag.axis 수평 방향(Drag.XAxis), 수직 방향(Drag.YAxis) 또는 양방향(Drag.XAndYAxis)으로 드래그할 수 있는지 여부를 지정하며,
• drag.minimum drag.maximum 는 대상 항목이 해당 축을 따라 드래그될 수 있는 최대 거리를 제한합니다.

다음 예제는 X축을 따라 드래그할 수 있는 Rectangle 을 표시합니다. 사각형을 오른쪽으로 드래그하면 투명도가 낮아집니다.

Rectangle {
    id: container
    width: 600; height: 200

    Rectangle {
        id: rect
        width: 50; height: 50
        color: "red"
        opacity: (600.0 - rect.x) / 600

        MouseArea {
            anchors.fill: parent
            drag.target: rect
            drag.axis: Drag.XAxis
            drag.minimumX: 0
            drag.maximumX: container.width - rect.width
        }
    }
}

drag.filterChildren 가 true로 설정된 경우, 드래그 작업이 하위 MouseArea를 재정의할 수 있습니다. 이를 통해 예를 들어, 상위 MouseArea 가 드래그를 처리하는 동안 하위 요소들은 클릭을 처리할 수 있습니다:

import QtQuick

Rectangle {
    width: 480
    height: 320
    Rectangle {
        x: 30; y: 30
        width: 300; height: 240
        color: "lightsteelblue"

        MouseArea {
            anchors.fill: parent
            drag.target: parent;
            drag.axis: "XAxis"
            drag.minimumX: 30
            drag.maximumX: 150
            drag.filterChildren: true

            Rectangle {
                color: "yellow"
                x: 50; y : 50
                width: 100; height: 100
                MouseArea {
                    anchors.fill: parent
                    onClicked: console.log("Clicked")
                }
            }
        }
    }
}

drag.threshold 드래그 작업이 시작되어야 하는 픽셀 단위의 임계값을 결정합니다. 기본적으로 이 값은 플랫폼에 따라 달라집니다. 이 속성은 Qt Quick 2.2에서 추가되었습니다.

drag.smoothed 가 true 인 경우, 드래그 작업이 시작된 후에만 대상이 이동됩니다. false 로 설정된 경우, 대상은 현재 마우스 위치로 바로 이동됩니다. 기본적으로 이 속성의 값은 true 입니다. 이 속성은 Qt Quick 2.4 버전에서 추가되었습니다.

드롭 기능을 구현하려면 Drag 첨부 속성과 DropArea 를 참조하십시오.

enabled : bool

이 속성은 해당 항목이 마우스 이벤트를 수신하는지 여부를 나타냅니다.

기본적으로 이 속성의 값은 true입니다.

hoverEnabled : bool

이 속성은 호버 이벤트가 처리되는지 여부를 결정합니다.

기본적으로 마우스 이벤트는 버튼 이벤트에 대한 반응으로, 즉 버튼이 눌렸을 때만 처리됩니다. 'hover'를 설정하면 마우스 버튼이 눌리지 않은 상태에서도 모든 마우스 이벤트를 처리할 수 있습니다.

이 속성은 ` containsMouse ` 속성과 `onEntered`, `onExited`, `onPositionChanged` 신호에 영향을 미칩니다.

이 속성들은 마우스 커서의 좌표를 저장합니다.

hoverEnabled 속성이 false인 경우, 이 속성들은 버튼이 눌려 있는 동안에만 유효하며, 마우스가 영역 밖으로 이동하더라도 버튼을 누르고 있는 한 계속 유효합니다.

기본적으로 이 속성은 false입니다.

hoverEnabled 가 true인 경우, 다음의 상황에서 이러한 속성이 유효합니다.

• 아무 버튼도 눌려 있지 않으나 마우스가 ' MouseArea ' 영역 내에 있을 때(`containsMouse `가 true인 경우).
• 버튼이 눌린 상태로 유지되는 경우(그 후 영역 밖으로 이동했더라도).

좌표는 ` MouseArea`을 기준으로 합니다.

pressAndHoldInterval : int

이 속성은 ` pressAndHold `이 발생하기 전까지의 경과 시간(밀리초 단위)을 재정의합니다.

명시적으로 설정되지 않았거나 재설정된 후에는 이 값이 ` QStyleHints::mousePressAndHoldInterval`을 따릅니다.

일반적으로 애플리케이션 스타일 힌트를 사용하여 이 속성을 전역적으로 설정하는 것으로 충분합니다. 이 속성은 특정 MouseAreas에 대해 다양한 간격이 필요한 경우에 사용해야 합니다.

pressAndHold도 참조하십시오 .

pressed : bool [read-only]

이 속성은 ‘ acceptedButtons ’ 중 현재 어느 키가 눌려 있는지 여부와 관계없이 유지됩니다.

pressedButtons : MouseButtons [read-only]

이 속성은 현재 눌려 있는 마우스 버튼을 저장합니다.

이 속성은 다음의 비트별 조합을 포함합니다:

• Qt.LeftButton
• Qt.RightButton
• Qt.MiddleButton

아래 코드는 마우스 오른쪽 버튼이 눌렸을 때 "right"를 표시합니다:

Text {
    text: mouseArea.pressedButtons & Qt.RightButton ? "right" : ""
    horizontalAlignment: Text.AlignHCenter
    verticalAlignment: Text.AlignVCenter

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        acceptedButtons: Qt.LeftButton | Qt.RightButton
    }
}

acceptedButtons도 참조하십시오 .

preventStealing : bool

이 속성은 이 ` MouseArea`에서 마우스 이벤트를 가로챌 수 있는지 여부를 나타냅니다.

MouseArea 가 Flickable과 같이 자식 마우스 이벤트를 필터링하는 항목 내에 배치된 경우, 부모 항목에서 제스처(예: 플릭 제스처)가 인식되면 MouseArea 에서 마우스 이벤트가 가로채질 수 있습니다. preventStealing이 true로 설정되어 있으면 어떤 항목도 마우스 이벤트를 가로채지 않습니다.

항목이 이미 이벤트 가로채기를 시작한 상태에서 preventStealing을 true로 설정하더라도, 다음 press 이벤트가 발생할 때까지는 아무런 효과가 없음을 유의하십시오.

기본적으로 이 속성은 false입니다.

propagateComposedEvents : bool

이 속성은 합성된 마우스 이벤트가 이 MouseArea 와 겹치지만 시각적 중첩 순서에서 더 아래에 있는 다른 MouseAreas로 자동으로 전파되는지 여부를 결정합니다. 기본적으로 이 속성의 값은 false입니다.

MouseArea 이 속성은 여러 가지 복합 이벤트( clicked, doubleClicked, pressAndHold)를 포함합니다. 이들은 pressed 와 같은 기본 마우스 이벤트로 구성되며, 기본 이벤트와는 다르게 전파될 수 있습니다.

propagateComposedEvents가 true로 설정된 경우, 복합 이벤트는 씬 내 동일한 위치에 있는 다른 MouseAreas로 자동으로 전파됩니다. 각 이벤트는 스택 순서상 바로 아래에 있는 enabled ( MouseArea )로 전파되며, MouseArea 가 이벤트를 수락할 때까지 이 시각적 계층 구조를 따라 아래로 전파됩니다. pressed 이벤트와 달리, 핸들러가 없는 경우 합성 이벤트는 자동으로 수락되지 않습니다.

예를 들어, 아래에는 파란색 Rectangle 를 포함하는 노란색 Rectangle 가 있습니다. 파란색 사각형은 시각적 중첩 순서 계층 구조에서 최상위 항목이므로, 노란색 사각형 위에 시각적으로 렌더링됩니다. 파란색 사각형은 propagateComposedEvents를 true로 설정하고, 수신된 모든 clicked 이벤트에 대해 MouseEvent::accepted 를 false로 설정하므로, 수신하는 모든 clicked 이벤트는 그 아래에 있는 노란색 사각형의 MouseArea 로 전파됩니다.

import QtQuick 2.0

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

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("clicked yellow")
    }

    Rectangle {
        color: "blue"
        width: 50; height: 50

        MouseArea {
            anchors.fill: parent
            propagateComposedEvents: true
            onClicked: (mouse)=> {
                console.log("clicked blue")
                mouse.accepted = false
            }
        }
    }
}

파란색 사각형을 클릭하면 자식 요소인 MouseArea 의 onClicked 핸들러가 호출되며, 이 이벤트는 노란색 사각형의 MouseArea 로 전파되어 해당 사각형의 onClicked 핸들러가 호출됩니다.

이 속성은 중첩된 MouseAreas가 복합 이벤트를 함께 처리하도록 하고자 할 때의 사용 사례를 크게 단순화합니다. 예를 들어, 한 MouseArea 가 clicked 신호를 처리하고 다른 가 pressAndHold 신호를 처리하도록 하거나, 한 MouseArea 가 대부분의 경우 clicked 신호를 처리하되 특정 조건이 충족될 때는 해당 신호를 전달하도록 하고자 할 때 유용합니다.

scrollGestureEnabled : bool

이 속성은 이 ` MouseArea `가 트랙패드의 두 손가락 플릭 제스처와 같은 마우스가 아닌 장치의 스크롤 제스처에 반응할지 여부를 제어합니다. `false`로 설정하면, ` wheel ` 신호는 휠이 있는 실제 마우스에서 휠 이벤트가 발생했을 때만 발송되며, 스크롤 제스처 이벤트는 이를 처리할 다른 `Item`으로 전달됩니다. 예를 들어, 사용자가 커서가 ` MouseArea`를 포함하는 항목 위에 있는 상태에서 플릭 제스처를 수행하여 그 아래에 있는 `Flickable`과 상호작용하려고 할 수 있습니다. 이 속성을 `false`로 설정하면 ` PinchArea `가 마우스 휠이나 핀치 제스처를 처리하고, `Flickable`은 플릭 제스처를 처리하게 됩니다.

기본적으로 이 속성의 값은 true입니다.

Signal 문서

canceled()

이 신호는 다른 항목이 마우스 이벤트 처리를 가로챈 탓에 마우스 이벤트가 취소되었을 때 발생합니다.

이 신호는 고급 용도로 사용됩니다. 입력을 처리하는 ` MouseArea `가 두 개 이상인 경우나, ` Flickable` 내부에 ` MouseArea `가 있는 경우에 유용합니다. 후자의 경우, ` onPressed ` 신호 핸들러에서 특정 로직을 실행한 후 드래그를 시작하면, ` Flickable `가 ` MouseArea`로부터 마우스 처리를 가로챌 것입니다. 이러한 경우, ` MouseArea `가 ` Flickable`에 마우스 처리를 넘겨준 후 로직을 재설정하려면, ` released` 외에도 ` canceled `를 처리해야 합니다.

clicked(MouseEvent mouse)

이 신호는 클릭이 발생했을 때 전송됩니다. 클릭이란 클릭 영역( MouseArea ) 내에서 버튼을 눌렀다가 놓는 동작을 말합니다(버튼을 누른 후 MouseArea 영역 밖으로 이동했다가 다시 안으로 들어와 놓는 경우도 클릭으로 간주됩니다).

mouse 매개변수는 클릭 해제 시점의 x 및 y 좌표, 클릭이 길게 누른 상태였는지 여부 등 클릭에 대한 정보를 제공합니다.

이 신호를 처리할 때, propagateComposedEvents 속성이 true 가 아닌 한, mouse 매개변수의 accepted 속성을 변경해도 아무런 효과가 없습니다.

doubleClicked(MouseEvent mouse)

이 신호는 더블 클릭(누른 후 떼었다가 다시 누르는 동작)이 발생했을 때 발생합니다. ` mouse ` 매개변수는 클릭이 떼어진 x 및 y 좌표와 클릭이 길게 눌렸는지 여부 등 클릭에 대한 정보를 제공합니다.

이 신호를 처리할 때, ` mouse ` 매개변수의 ` accepted ` 속성이 `false`로 설정되어 있으면 두 번째 클릭에 대해 `pressed`/`released`/`clicked` 신호가 발생하지만, 그렇지 않으면 이러한 신호가 억제됩니다. ` accepted ` 속성의 기본값은 `true`입니다.

entered()

이 신호는 마우스가 마우스 영역에 들어올 때 발생합니다.

기본적으로 이 신호는 현재 버튼이 눌려 있는 경우에만 발생합니다. 마우스 버튼이 눌려 있지 않은 상태에서도 이 신호가 발생하도록 하려면 ` hoverEnabled `을 true로 설정하십시오.

hoverEnabled도 참조하십시오 .

exited()

이 신호는 마우스가 마우스 영역을 벗어날 때 발생합니다.

기본적으로 이 신호는 마우스 버튼이 눌려 있는 경우에만 발생합니다. 마우스 버튼이 눌려 있지 않은 상태에서도 이 신호가 발생하도록 하려면 hoverEnabled 를 true로 설정하십시오.

아래 예제는 두 개의 MouseArea 간의 꽤 전형적인 관계를 보여주며, mouseArea2 가 mouseArea1 위에 위치해 있습니다. mouseArea1 에서 mouseArea2 로 마우스를 이동하면 mouseArea1 에서 exited 신호가 발생합니다.

Rectangle {
    width: 400; height: 400
    MouseArea {
        id: mouseArea1
        anchors.fill: parent
        hoverEnabled: true
    }
    MouseArea {
        id: mouseArea2
        width: 100; height: 100
        anchors.centerIn: parent
        hoverEnabled: true
    }
}

반대로 두 MouseArea에 부모-자식 관계를 설정하면, mouseArea1 에서 mouseArea2 로 마우스를 이동해도 mouseArea1 에서 exited 신호가 발생하지 않습니다. 대신, 두 영역 모두에 동시에 마우스가 호버된 것으로 간주됩니다.

hoverEnabled도 참조하십시오 .

positionChanged(MouseEvent mouse)

이 신호는 마우스 위치가 변경될 때 발생합니다.

mouse 매개변수는 x 및 y 좌표를 비롯해 현재 눌려 있는 버튼 정보 등 마우스에 대한 정보를 제공합니다.

기본적으로 이 신호는 현재 버튼이 눌려 있는 경우에만 발생합니다. 마우스 버튼이 눌려 있지 않은 경우에도 이 신호가 발생하도록 하려면 hoverEnabled 를 true로 설정하십시오.

이 신호를 처리할 때, mouse 매개변수의 accepted 속성을 변경해도 아무런 효과가 없습니다.

pressAndHold(MouseEvent mouse)

이 신호는 길게 누르는 동작(현재 800ms)이 발생했을 때 발생합니다. ` mouse ` 매개변수는 누른 위치의 x 및 y 좌표와 어떤 버튼이 눌렸는지를 포함하여 누름 동작에 대한 정보를 제공합니다.

이 신호를 처리할 때, ` propagateComposedEvents ` 속성이 ` true`로 설정되어 있지 않은 한, ` mouse ` 매개변수의 ` accepted ` 속성을 변경해도 아무런 효과가 없습니다.

pressed(MouseEvent mouse)

이 신호는 버튼이 눌렸을 때 발생합니다. ‘ mouse ’ 매개변수는 x 및 y 좌표와 눌린 버튼 종류를 포함하여 버튼 누름에 대한 정보를 제공합니다.

이 신호를 처리할 때는 ` mouse ` 매개변수의 ` accepted ` 속성을 사용하여, 이 ` MouseArea `가 해당 누름 이벤트와 버튼이 놓일 때까지 발생하는 모든 향후 마우스 이벤트를 처리할지 여부를 제어할 수 있습니다. 기본값은 이벤트를 수락하고, 이 영역 아래에 있는 다른 `MouseAreas`가 해당 이벤트를 처리하지 못하도록 하는 것입니다. `accepted` 가 `false`로 설정된 경우, 버튼이 다시 눌릴 때까지 이 ` MouseArea `로 더 이상 이벤트가 전송되지 않습니다.

released(MouseEvent mouse)

이 신호는 클릭이 해제될 때 발생합니다. ` mouse ` 매개변수는 클릭 해제 시의 x 및 y 좌표와 클릭이 길게 눌렸는지 여부 등 클릭에 대한 정보를 제공합니다.

이 신호를 처리할 때, ` mouse ` 매개변수의 ` accepted ` 속성을 변경해도 아무런 효과가 없습니다.

canceled도 참조하십시오 .

wheel(WheelEvent wheel)

이 신호는 마우스 휠과 트랙패드의 스크롤 제스처 모두에 반응하여 발생합니다.

wheel 매개변수는 x 및 y 좌표, 현재 눌려 있는 버튼, angleDelta 및 pixelDelta를 포함한 휠 움직임 정보 등 이벤트에 대한 정보를 제공합니다.