포인터 이벤트는 포인팅 기기와의 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}");
}
}
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.