포인터 이벤트는 포인팅 기기와의 UI 상호작용 시 발생합니다. 마우스 이벤트와 마찬가지로, 포인터 이벤트는 사용된 입력 기기에 대한 추가 정보(예: 펜 압력, 기울기 각도)를 제공합니다.
UI 툴킷에서 포인터 이벤트는 항상 마우스 이벤트보다 앞섭니다.
포인터 이벤트에는 영구적인 포지션이 없습니다. 또한 터치 기기에서 놓을 때 설정된 포지션이 없습니다.
PointerStationaryEvent 및 PointerCancelEvent 이벤트와 같은 일부 포인터 이벤트에는 입력 기기의 운영체제(OS)에 의해 트리거되는 조건이 있습니다.
모든 포인터 이벤트의 기본 클래스는 PointerEventBase입니다.
| 이벤트 | 설명 | 트리클다운 | 버블업 | 취소 가능 |
|---|---|---|---|---|
| PointerDownEvent | 포인터를 누를 때 전송됩니다. | 지원 | 지원 | 지원 |
| PointerUpEvent | 포인터를 놓을 때 전송됩니다. | 지원 | 지원 | 지원 |
| PointerMoveEvent | 포인터 상태가 변경될 때 전송됩니다. | 지원 | 지원 | 지원 |
| PointerEnterEvent | 포인터가 시각적 요소 또는 요소의 자손에 들어갈 때 전송됩니다. | 지원 | 지원 | |
| PointerLeaveEvent | 포인터가 시각적 요소 및 해당 요소의 모든 자손을 떠날 때 전송됩니다. | 지원 | 지원 | |
| PointerOverEvent | 포인터가 시각적 요소에 들어갈 때 전송됩니다. | 지원 | 지원 | 지원 |
| PointerOutEvent | 포인터가 시각적 요소를 떠날 때 전송됩니다. | 지원 | 지원 | 지원 |
| PointerStationaryEvent | 스타일러스나 손가락 등 포인터 타입이 운영체제에서 정한 시간 내에 변경되지 않으면 전송됩니다. | 지원 | 지원 | 지원 |
| PointerCancelEvent | 운영체제에서 포인터 작업을 취소할 때 전송됩니다. | 지원 | 지원 | 지원 |
altitudeAngle: heightAngle에는 표면을 기준으로 한 스타일러스 각도(라디안 단위)가 포함됩니다. 값이 0이면 스타일러스가 표면과 평행함을 나타내고, 값이 pi/2이면 표면에 대해 수직임을 나타냅니다.
azimuthAngle: azimuthAngle에는 x축을 기준으로 한 스타일러스 각도(라디안 단위)가 포함됩니다. 값이 0이면 스타일러스가 기기의 x축과 평행함을 나타냅니다.
button: button 프로퍼티는 이벤트를 트리거하기 위해 누른 마우스 버튼을 식별하는 정수를 반환합니다. 다음 표에는 정수 및 관련 마우스 버튼이 나열되어 있습니다.
| 정수 | 버튼 |
|---|---|
| 0 | 왼쪽 버튼 |
| 1 | 오른쪽 버튼 |
| 2 | 가운데 버튼 |
clickCount: clickCount 프로퍼티에는 버튼을 누른 횟수가 포함되어 있습니다.
deltaPosition: deltaPosition 프로퍼티에는 이전 마우스 이벤트 동안의 포인터 포지션과 현재 마우스 이벤트 동안의 포인터 포지션 간의 차이가 포함되어 있습니다.
deltaTime: deltaTime 프로퍼티에는 포인터 값의 마지막 기록 변경 이후 경과된 시간(초)이 포함되어 있습니다.
localPosition: localPosition 프로퍼티는 타겟 시각적 요소를 기준으로 포인터 포지션을 반환합니다.
modifiers: modifiers 프로퍼티는 현재 누르고 있는 수정 키를 반환합니다. 수정자의 몇 가지 예로는 Shift, Ctrl 또는 Alt 키입니다. 자세한 내용은 MDN 문서의 수정 키 섹션을 참조하십시오.
pointerId: pointerId 프로퍼티는 이벤트를 전송하는 포인터를 식별하는 정수를 반환합니다.
pointerType: pointerType 프로퍼티는 이벤트를 생성하는 포인터 타입을 정의하는 문자열을 반환합니다.
position: position 프로퍼티는 화면 또는 월드 좌표 시스템에 있는 포인터 포지션을 반환합니다.
pressedButtons: pressedButton 프로퍼티는 현재 누른 마우스 버튼 조합을 식별하는 정수를 반환합니다.
숫자는 개별 버튼의 정수 값의 합계입니다(아래 표 참조). 예를 들어 마우스 오른쪽 버튼과 마우스 가운데 버튼을 동시에 누르고 있으면 pressButton의 값은 6이 됩니다.
| 정수 | 버튼 |
|---|---|
| 1 | 왼쪽 버튼 |
| 2 | 오른쪽 버튼 |
| 4 | 가운데 버튼 |
pressure: pressure 프로퍼티는 현재 터치가 가하는 압력의 양을 반환합니다. 기기가 압력을 보고하지 않는 경우 이 프로퍼티 값은 1.0f입니다.
radius: radius 프로퍼티는 터치 반지름의 근사치를 반환합니다. 최대 터치 반지름을 얻으려면 radiusVariance를 더하고, 최소 터치 반지름을 얻으려면 radiusVariance를 빼십시오.
radiusVariance: radiusVariance 프로퍼티 값은 터치 반지름의 정확도를 결정합니다. 최대 터치 반지름을 얻으려면 이 값을 반지름에 더하고, 최소 터치 반지름을 얻으려면 이 값을 반지름에서 빼십시오.
tangentialPressure: tangentialPressure 프로퍼티는 스타일러스의 추가 압력 감지 컨트롤에 가해진 압력을 나타내는 플로트 값을 반환합니다.
twist: twist 프로퍼티는 축을 중심으로 한 스타일러스의 회전(라디안 단위)을 반환합니다.
다음 리스트는 이벤트 패밀리에 있는 각 이벤트의 이름, 설명 및 타겟을 제공합니다. 이벤트에 대한 자세한 내용은 UI 툴킷 API를 참조하십시오.
PointerDownEvent는 시각적 요소 내에서 포인터를 누를 때 전송됩니다.
target: 포인터 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서 아래에서 선택 가능한 최상위 요소입니다.
PointerUpEvent는 시각적 요소 내에서 포인터를 뗄 때 트리거됩니다.
PointerUpEvent이벤트가 트리거되면 포인터 좌표도 제거됩니다. 또한 포인터의 캐시가 지워지므로 포인터 위치에 대한 기록도 없습니다.
target: 포인터 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서 아래에서 선택 가능한 최상위 요소입니다.
PointerMoveEvent는 포인터 상태가 변경될 때 발생합니다.
target: 포인터 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서 아래에서 선택 가능한 최상위 요소입니다.
PointerEnterEvent는 포인터가 시각적 요소 또는 그 자손 중 하나에 들어갈 때 전송됩니다.
target: 포인터가 나가는 시각적 요소(또는 그 자손 중 하나)입니다.
PointerLeaveEvent는 포인터가 시각적 요소와 그 자손 모두에서 나갈 때 전송됩니다. 예를 들어 시각적 요소에 자식이 포함되어 있고 포인터가 부모 또는 자식 위에 더 이상 있지 않으면 부모 요소는 이 이벤트를 수신합니다. 포인터가 여전히 자식 요소 중 하나 위에 있는 동안에는 부모 요소가 PointerLeaveEvent를 수신하지 않으며, 이는 더 이상 포인터 아래의 최상위 요소가 아닌 경우 마찬가지입니다. 대신에 PointerOverEvent를 수신합니다.
target: 포인터가 나가는 시각적 요소(또는 그 자손 중 하나)입니다.
PointerOverEvent는 포인터가 시각적 요소에 들어갈 때 전송됩니다.
target: 포인터 아래에 있는 시각적 요소입니다.
PointerOutEvent는 포인터가 시각적 요소에서 나갈 때 전송됩니다.
target: 포인터가 있는 시각적 요소입니다.
PointerStationaryEvent는 포인터 타입(예: 스타일러스, 손가락)이 운영체제에서 결정한 일정 시간 동안 변경되지 않을 때 전송됩니다.
target: 포인터를 캡처하는 시각적 요소, 또는 포인터 아래에서 선택 가능한 최상위 요소입니다.
PointerCancelEvent는 운영체제에서 포인터 작업을 취소할 때 전송됩니다.
target: 포인터를 캡처하는 시각적 요소, 또는 포인터 아래에서 선택 가능한 최상위 요소입니다.
다음 코드 샘플은 노란색 상자가 포함된 빨간색 상자가 있는 에디터 창을 생성합니다. 포인터가 시각적 요소 또는 그 자식을 떠날 때 콘솔에 메시지를 출력합니다. 이 예제는 PointerOutEvent 및 PointerLeaveEvent의 동작을 시연합니다.
예제가 동작하는 방식을 확인하려면 다음 단계를 따르십시오.
<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements" xsi="http://www.w3.org/2001/XMLSchema-instance" engine="UnityEngine.UIElements" editor="UnityEditor.UIElements" noNamespaceSchemaLocation="../../UIElementsSchema/UIElements.xsd" editor-extension-mode="False">
<ui:VisualElement style="flex-grow: 1; justify-content: center; align-items: center;">
<ui:VisualElement name="Red_Box" style="background-color: rgb(183, 34, 46); width: 50%; height: 50%; align-items: center; justify-content: center;">
<ui:VisualElement name="Yellow_Box" style="width: 175%; height: 50%; background-color: rgb(197, 163, 0);" />
</ui:VisualElement>
</ui:VisualElement>
</ui:UXML>
using UnityEditor;
using UnityEngine;
using UnityEngine.UIElements;
using UnityEditor.UIElements;
public class PointerEventsTestWindow : EditorWindow
{
[MenuItem("Window/UI Toolkit/Pointer Events Test Window")]
public static void ShowExample()
{
PointerEventsTestWindow wnd = GetWindow<PointerEventsTestWindow>();
wnd.titleContent = new GUIContent("Pointer Events Test Window");
}
public void CreateGUI()
{
// Import UXML
VisualTreeAsset visualTree = AssetDatabase.LoadAssetAtPath<VisualTreeAsset>("Assets/Scripts/Editor/PointerEventsTestWindow.uxml");
visualTree.CloneTree(rootVisualElement);
// Get the red box and register pointer event callbacks
VisualElement redBox = rootVisualElement.Q("Red_Box");
redBox.RegisterCallback<PointerOutEvent>(OnPointerOutEvent, TrickleDown.TrickleDown);
redBox.RegisterCallback<PointerLeaveEvent>(OnPointerLeaveEvent, TrickleDown.TrickleDown);
}
private void OnPointerLeaveEvent(PointerLeaveEvent evt)
{
Debug.Log($"Pointer LEAVE Event. Target: {(evt.target as VisualElement).name}");
}
private void OnPointerOutEvent(PointerOutEvent evt)
{
Debug.Log($"Pointer OUT Event. Target: {(evt.target as VisualElement).name}");
}
}