마우스 이벤트는 마우스를 사용하여 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}");
}
}
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.