마우스 이벤트는 마우스를 사용하여 UI와 상호 작용할 때 발생합니다. 터치, 펜 또는 기타 포인팅 기기는 마우스 이벤트가 아닌 다른 이벤트를 생성합니다. 마우스 이벤트 API와 이 기술 자료에서 ’마우스’라는 용어는 물리적 마우스 또는 물리적 마우스를 에뮬레이트하는 가상 마우스를 의미합니다.
마우스 이벤트에는 항상 해당하는 PointerEvent가 선행합니다.
모든 마우스 이벤트의 기본 클래스는 MouseEventBase입니다.
| 이벤트 | 설명 | 트리클다운 | 버블업 | 취소 가능 |
|---|---|---|---|---|
| MouseDownEvent | 사용자가 마우스 버튼을 누를 때 전송됩니다. | 지원 | 지원 | 지원 |
| MouseUpEvent | 사용자가 마우스 버튼을 놓을 때 전송됩니다. | 지원 | 지원 | 지원 |
| MouseMoveEvent | 사용자가 마우스를 움직일 때 전송됩니다. | 지원 | 지원 | 지원 |
| WheelEvent | 사용자가 마우스 휠을 활성화할 때 전송됩니다. | 지원 | 지원 | 지원 |
| MouseEnterWindowEvent | 마우스가 창에 들어갈 때 전송됩니다. | 지원 | ||
| MouseLeaveWindowEvent | 마우스가 창을 떠날 때 전송됩니다. | 지원 | ||
| MouseEnterEvent | 마우스가 요소 또는 요소의 자손에 들어갈 때 전송됩니다. | 지원 | 지원 | |
| MouseLeaveEvent | 마우스가 요소 또는 요소의 자손을 떠날 때 전송됩니다. | 지원 | 지원 | |
| MouseOverEvent | 마우스가 요소에 들어갈 때 전송됩니다. | 지원 | 지원 | 지원 |
| MouseOutEvent | 마우스가 요소를 떠날 때 전송됩니다. | 지원 | 지원 | 지원 |
| ContextClickEvent(더 이상 사용되지 않음) | 사용자가 세 번째 마우스 버튼을 누르거나 놓을 때 전송됩니다. 이전 버전 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}");
}
}