마우스 이벤트는 마우스를 사용하여 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는 커서가 시각적 요소 안에 있는 동안 마우스 버튼을 누를 때 전송됩니다.
target: 마우스 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서 아래에서 선택 가능한 최상위 요소입니다.
MouseUpEvent는 커서가 시각적 요소 안에 있는 동안 마우스 버튼을 놓을 때 트리거됩니다. MouseUpEvent는 MouseDownEvent와 보완적 관계입니다.
target: 마우스 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서 아래에서 선택 가능한 최상위 요소입니다.
MouseMoveEvent는 커서 핫스팟이 시각적 요소 안에서 이동할 때 전송됩니다.
target: 마우스 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서 아래에서 선택 가능한 최상위 요소입니다.
WheelEvent는 마우스 휠을 누를 때 전송됩니다.
target: 마우스 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서 아래에서 선택 가능한 최상위 요소입니다.
MouseEnterWindowEvent는 커서가 에디터 창에 들어갈 때 트리거됩니다. 런타임 패널은 게임 뷰 창에 들어갈 때 이 이벤트를 수신하지 않습니다.
target: 마우스 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서 아래에서 선택 가능한 최상위 요소입니다.
MouseLeaveWindowEvent는 커서가 에디터 창의 공간에서 나갈 때 발생합니다. MouseLeaveWindowEvent는 MouseEnterWindowEvent와 대조적 관계입니다.
target: 마우스 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서가 요소 위에 있지 않으므로 null을 반환합니다.
MouseEnterEvent는 커서가 시각적 요소 또는 그 자손 중 하나에 들어갈 때 전송됩니다.
target: 마우스 커서 또는 그 자손 중 하나의 아래에 있는 시각적 요소입니다.
MouseLeaveEvent는 커서가 시각적 요소에서 나갈 때 트리거됩니다. 이 이벤트는 마우스가 나가는 각 요소로 전송되기 때문에 MouseOutEvent와는 다릅니다. 이 이벤트는 전파되지 않습니다.
target: 마우스 커서가 나가는 시각적 요소(또는 그 자손 중 하나)입니다.
MouseOverEvent는 커서가 요소에 들어갈 때 전송됩니다. 이 이벤트는 들어간 요소에만 전송되기 때문에 MouseEnterEvent와는 다릅니다.
target: 마우스 커서 아래에 있는 시각적 요소입니다.
MouseOutEvent는 포인팅 기기가 시각적 요소의 경계 밖으로 커서를 이동할 때 트리거됩니다.
MouseOutEvent는 MouseLeaveEvent와 다릅니다. MouseOutEvent는 시각적 요소에서 다른 요소로 떠날 때 전송되는 반면, MouseLeaveEvent는 시각적 요소에서 자손 요소로 전환할 때 전송되지 않습니다.
target: 마우스 커서가 나간 시각적 요소입니다.
컨텍스트 메뉴를 메뉴 항목으로 채워야 할 때 ContextualMenuManager가 전송하는 이벤트입니다.
target: 컨텍스트 메뉴가 빌드되는 시각적 요소입니다.
사용자가 세 번째 마우스 버튼을 누르거나 손을 뗄 때 전송되는 이벤트입니다. 이 이벤트는 IMGUI와 이전 버전과의 호환성을 위해서만 존재합니다.
다음 코드 샘플은 마우스 커서가 요소 위로 이동하거나 마우스 버튼을 누를 때 콘솔에 메시지를 출력하는 세 개의 버튼이 있는 에디터 창을 생성합니다.
이 코드 샘플은 MouseDownEvent 및 MouseEnterEvent 이벤트 발생과 이벤트 파라미터의 사용 방법을 강조합니다.
예제가 동작하는 방식을 확인하려면 다음 단계를 따르십시오.
MouseEventTestWindow.cs라는 새 C# 스크립트를 생성합니다.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에 대한 콜백 등록과 이벤트 파라미터의 사용 방법을 강조합니다.
예제가 동작하는 방식을 확인하려면 다음 단계를 따르십시오.
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}");
}
}