마우스 이벤트

마우스 이벤트는 마우스를 사용하여 UI와 상호작용할 때 발생합니다. 터치, 펜 또는 기타 포인팅 기기는 마우스 이벤트가 아니라 다른 이벤트를 생성합니다. 마우스 이벤트 API와 이 문서에서 ’마우스’라는 용어는 물리적 마우스, 또는 물리적 마우스를 에뮬레이트하는 가상 마우스만 의미합니다.

마우스 이벤트에는 항상 PointerEvent가 선행합니다.

모든 마우스 이벤트의 기본 클래스는 MouseEventBase입니다.

이벤트	설명	트리클다운	버블업	취소 가능
MouseDownEvent	사용자가 마우스 버튼을 누를 때 전송됩니다.	지원	지원	지원
MouseUpEvent	사용자가 마우스 버튼을 놓을 때 전송됩니다.	지원	지원	지원
MouseMoveEvent	사용자가 마우스를 움직일 때 전송됩니다.	지원	지원	지원
WheelEvent	사용자가 마우스 휠을 활성화할 때 전송됩니다.	지원	지원	지원
MouseEnterWindowEvent	마우스가 창에 들어갈 때 전송됩니다.			지원
MouseLeaveWindowEvent	마우스가 창에서 나갈 때 전송됩니다.			지원
MouseEnterEvent	마우스가 요소 또는 그 자손 중 하나에 들어갈 때 전송됩니다.	지원		지원
MouseLeaveEvent	마우스가 요소 또는 그 자손 중 하나에서 나갈 때 전송됩니다.	지원		지원
MouseOverEvent	마우스가 요소에 들어갈 때 전송됩니다.	지원	지원	지원
MouseOutEvent	마우스가 요소에서 나갈 때 전송됩니다.	지원	지원	지원
ContextClickEvent (obsolete)	사용자가 세 번째 마우스 버튼을 누르거나 손을 뗄 때 전송됩니다. 이 이벤트는 IMGUI와 이전 버전과의 호환성을 위해서만 존재합니다.	지원	지원	지원

고유한 프로퍼티

button: button 프로퍼티는 이벤트를 트리거하기 위해 누른 마우스 버튼을 식별하는 정수를 반환합니다. 다음 표에는 정수 및 관련 마우스 버튼이 나열되어 있습니다.

정수	버튼
0	왼쪽 버튼
1	오른쪽 버튼
2	가운데 버튼

pressedButtons: pressedButton 프로퍼티는 현재 누른 마우스 버튼 조합을 식별하는 정수를 반환합니다.

숫자는 개별 버튼의 정수 값의 합계입니다(아래 표 참조). 예를 들어 마우스 오른쪽 버튼과 마우스 가운데 버튼을 동시에 누르고 있으면 pressButton의 값은 6이 됩니다.

정수	버튼
1	왼쪽 버튼
2	오른쪽 버튼
4	가운데 버튼

modifiers: modifiers 프로퍼티는 키보드 이벤트 동안 누른 수정 키를 반환합니다. 수정자의 몇 가지 예로는 Shift, Ctrl 또는 Alt 키가 있습니다.

자세한 내용은 MDN 문서의 수정 키 섹션을 참조하십시오.

mousePosition: mousePosition 프로퍼티는 화면 좌표 시스템이라고도 부르는 패널 내 마우스 포지션을 반환합니다. 패널 좌표에 대한 자세한 내용은 시각적 트리 페이지를 참조하십시오.

localMousePosition: localMousePosition 프로퍼티는 타겟 시각적 요소를 기준으로 좌표를 반환합니다.

mouseDelta: 이전 마우스 이벤트 동안의 포인터 포지션과 현재 마우스 이벤트 동안의 포인터 포지션 간의 차이입니다.

이벤트 리스트

다음 리스트는 이벤트 패밀리에 있는 각 이벤트의 이름, 설명 및 타겟을 제공합니다. 이벤트에 대한 자세한 내용은 UI 툴킷 API를 참조하십시오.

MouseDownEvent

MouseDownEvent는 커서가 시각적 요소 안에 있는 동안 마우스 버튼을 누를 때 전송됩니다.

target: 마우스 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서 아래에서 선택 가능한 최상위 요소입니다.

MouseUpEvent

MouseUpEvent는 커서가 시각적 요소 안에 있는 동안 마우스 버튼을 놓을 때 트리거됩니다. MouseUpEvent는 MouseDownEvent와 보완적 관계입니다.

target: 마우스 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서 아래에서 선택 가능한 최상위 요소입니다.

MouseMoveEvent

MouseMoveEvent는 커서 핫스팟이 시각적 요소 안에서 이동할 때 전송됩니다.

target: 마우스 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서 아래에서 선택 가능한 최상위 요소입니다.

WheelEvent

WheelEvent는 마우스 휠을 누를 때 전송됩니다.

target: 마우스 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서 아래에서 선택 가능한 최상위 요소입니다.

MouseEnterWindowEvent

MouseEnterWindowEvent는 커서가 에디터 창에 들어갈 때 트리거됩니다. 런타임 패널은 게임 뷰 창에 들어갈 때 이 이벤트를 수신하지 않습니다.

target: 마우스 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서 아래에서 선택 가능한 최상위 요소입니다.

MouseLeaveWindowEvent

MouseLeaveWindowEvent는 커서가 에디터 창의 공간에서 나갈 때 발생합니다. MouseLeaveWindowEvent는 MouseEnterWindowEvent와 대조적 관계입니다.

target: 마우스 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서가 요소 위에 있지 않으므로 null을 반환합니다.

MouseEnterEvent

MouseEnterEvent는 커서가 시각적 요소 또는 그 자손 중 하나에 들어갈 때 전송됩니다.

target: 마우스 커서 또는 그 자손 중 하나의 아래에 있는 시각적 요소입니다.

MouseLeaveEvent

MouseLeaveEvent는 커서가 시각적 요소에서 나갈 때 트리거됩니다. 이 이벤트는 마우스가 나가는 각 요소로 전송되기 때문에 MouseOutEvent와는 다릅니다. 이 이벤트는 전파되지 않습니다.

target: 마우스 커서가 나가는 시각적 요소(또는 그 자손 중 하나)입니다.

MouseOverEvent

MouseOverEvent는 커서가 요소에 들어갈 때 전송됩니다. 이 이벤트는 들어간 요소에만 전송되기 때문에 MouseEnterEvent와는 다릅니다.

target: 마우스 커서 아래에 있는 시각적 요소입니다.

MouseOutEvent

MouseOutEvent는 포인팅 기기가 시각적 요소의 경계 밖으로 커서를 이동할 때 트리거됩니다.

MouseOutEvent는 MouseLeaveEvent와 다릅니다. MouseOutEvent는 시각적 요소에서 다른 요소로 떠날 때 전송되는 반면, MouseLeaveEvent는 시각적 요소에서 자손 요소로 전환할 때 전송되지 않습니다.

target: 마우스 커서가 나간 시각적 요소입니다.

ContextualMenuPopulateEvent

컨텍스트 메뉴를 메뉴 항목으로 채워야 할 때 ContextualMenuManager가 전송하는 이벤트입니다.

target: 컨텍스트 메뉴가 빌드되는 시각적 요소입니다.

ContextClickEvent(더 이상 사용되지 않음)

사용자가 세 번째 마우스 버튼을 누르거나 손을 뗄 때 전송되는 이벤트입니다. 이 이벤트는 IMGUI와 이전 버전과의 호환성을 위해서만 존재합니다.

예제

에디터 창 예제

다음 코드 샘플은 마우스 커서가 요소 위로 이동하거나 마우스 버튼을 누를 때 콘솔에 메시지를 출력하는 세 개의 버튼이 있는 에디터 창을 생성합니다.

이 코드 샘플은 MouseDownEvent 및 MouseEnterEvent 이벤트 발생과 이벤트 파라미터의 사용 방법을 강조합니다.

예제가 동작하는 방식을 확인하려면 다음 단계를 따르십시오.

1. Create a new C# script called MouseEventTestWindow.cs.
2. 예제를 복사하여 C# 스크립트에 붙여넣습니다.
3. Window > UI Toolkit > Mouse Event Test Window에서 예제를 엽니다.

using UnityEditor;
using UnityEngine;
using UnityEngine.UIElements;

// Open this in the Editor via the menu Window > UI ToolKit > Mouse Event Test Window
public class MouseEventTestWindow : EditorWindow
{
    [MenuItem("Window/UI Toolkit/Mouse Event Test Window")]
    public static void ShowExample()
    {
        MouseEventTestWindow wnd = GetWindow<MouseEventTestWindow>();
        wnd.titleContent = new GUIContent("Mouse Event Test Window");
    }
    public void CreateGUI()
    {
        // Add a few buttons
        for (int i = 0; i < 3; i++)
        {
            Button newElement = new Button { name = $"Button {i}", text = $"Button {i}" };
            newElement.style.flexGrow = 1;
            rootVisualElement.Add(newElement);
        }
        // Register mouse event callbacks
        rootVisualElement.RegisterCallback<MouseDownEvent>(OnMouseDown, TrickleDown.TrickleDown);
        rootVisualElement.RegisterCallback<MouseEnterEvent>(OnMouseEnter, TrickleDown.TrickleDown);
    }

    private void OnMouseDown(MouseDownEvent evt)
    {
        bool leftMouseButtonPressed = 0 != (evt.pressedButtons & (1 << (int)MouseButton.LeftMouse));
        bool rightMouseButtonPressed = 0 != (evt.pressedButtons & (1 << (int)MouseButton.RightMouse));
        bool middleMouseButtonPressed = 0 != (evt.pressedButtons & (1 << (int)MouseButton.MiddleMouse));
        Debug.Log($"Mouse Down event. Triggered by {(MouseButton)evt.button}.");
        Debug.Log($"Pressed buttons: Left button: {leftMouseButtonPressed} Right button: {rightMouseButtonPressed} Middle button: {middleMouseButtonPressed}");
    }

    private void OnMouseEnter(MouseEnterEvent evt)
    {
        VisualElement targetElement = (VisualElement)evt.target;
        Debug.Log($"Mouse is now over element '{targetElement.name}'");
    }
}

런타임 예제

다음 코드 샘플은 마우스 버튼을 누를 때 콘솔에 메시지를 출력하여, 이벤트를 트리거한 버튼과 현재 누른 버튼을 보여줍니다.

이 코드 샘플은 MouseDownEvent에 대한 콜백 등록과 이벤트 파라미터의 사용 방법을 강조합니다. 예제가 동작하는 방식을 확인하려면 다음 단계를 따르십시오.

1. 유효한 UIDocument를 사용하여 게임 오브젝트를 만듭니다.
2. Assets > Scripts에서 MouseEventTestRuntime이라는 C# 스크립트를 작성합니다.
3. 예제를 복사하여 C# 스크립트에 붙여넣습니다.
4. UIDocument를 사용하여 MouseEventTestRuntime 스크립트를 게임 오브젝트에 연결합니다.
5. 플레이 모드를 시작합니다.
6. 마우스 커서를 게임 뷰 위로 이동한 후 마우스 버튼을 누르거나 누른 채로 유지합니다.

using UnityEngine;
using UnityEngine.UIElements;

public class MouseEventTestRuntime : MonoBehaviour
{
    void Start()
    {
        var root = GetComponent<UIDocument>().rootVisualElement;
        var newLabel = new Label("Move the mouse or press buttons to see the log output");
        newLabel.style.flexGrow = 1;
        root.Add(newLabel);
        root.RegisterCallback<MouseDownEvent>(OnMouseDown, TrickleDown.TrickleDown);
    }

    private void OnMouseDown(MouseDownEvent evt)
    {
        bool leftMouseButtonPressed = 0 != (evt.pressedButtons & (1 << (int)MouseButton.LeftMouse));
        bool rightMouseButtonPressed = 0 != (evt.pressedButtons & (1 << (int)MouseButton.RightMouse));
        bool middleMouseButtonPressed = 0 != (evt.pressedButtons & (1 << (int)MouseButton.MiddleMouse));

        VisualElement targetElement = (VisualElement)evt.target;
        Debug.Log($"Mouse Down event. Triggered by {(MouseButton)evt.button} over element '{targetElement.name}'");
        Debug.Log($"Pressed buttons: Left button: {leftMouseButtonPressed} Right button: {rightMouseButtonPressed} Middle button: {middleMouseButtonPressed}");
    }
}