Version: 2023.1
언어: 한국어
패널 이벤트
툴팁 이벤트

포인터 이벤트

포인터 이벤트는 포인팅 기기와의 UI 상호작용 시 발생합니다. 마우스 이벤트와 마찬가지로, 포인터 이벤트는 사용된 입력 기기에 대한 추가 정보(예: 펜 압력, 기울기 각도)를 제공합니다.

UI 툴킷에서 포인터 이벤트는 항상 마우스 이벤트보다 앞섭니다.

포인터 이벤트에는 영구적인 포지션이 없습니다. 또한 터치 기기에서 놓을 때 설정된 포지션이 없습니다.

PointerStationaryEventPointerCancelEvent 이벤트와 같은 일부 포인터 이벤트에는 입력 기기의 운영체제(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

PointerDownEvent는 시각적 요소 내에서 포인터를 누를 때 전송됩니다.

target: 포인터 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서 아래에서 선택 가능한 최상위 요소입니다.

PointerUpEvent

PointerUpEvent는 시각적 요소 내에서 포인터를 뗄 때 트리거됩니다.

PointerUpEvent이벤트가 트리거되면 포인터 좌표도 제거됩니다. 또한 포인터의 캐시가 지워지므로 포인터 위치에 대한 기록도 없습니다.

target: 포인터 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서 아래에서 선택 가능한 최상위 요소입니다.

PointerMoveEvent

PointerMoveEvent는 포인터 상태가 변경될 때 발생합니다.

target: 포인터 캡처를 수신하는 시각적 요소입니다. 그렇지 않으면 커서 아래에서 선택 가능한 최상위 요소입니다.

PointerEnterEvent

PointerEnterEvent는 포인터가 시각적 요소 또는 그 자손 중 하나에 들어갈 때 전송됩니다.

target: 포인터가 나가는 시각적 요소(또는 그 자손 중 하나)입니다.

PointerLeaveEvent

PointerLeaveEvent는 포인터가 시각적 요소와 그 자손 모두에서 나갈 때 전송됩니다. 예를 들어 시각적 요소에 자식이 포함되어 있고 포인터가 부모 또는 자식 위에 더 이상 있지 않으면 부모 요소는 이 이벤트를 수신합니다. 포인터가 여전히 자식 요소 중 하나 위에 있는 동안에는 부모 요소가 PointerLeaveEvent를 수신하지 않으며, 이는 더 이상 포인터 아래의 최상위 요소가 아닌 경우 마찬가지입니다. 대신에 PointerOverEvent를 수신합니다.

target: 포인터가 나가는 시각적 요소(또는 그 자손 중 하나)입니다.

PointerOverEvent

PointerOverEvent는 포인터가 시각적 요소에 들어갈 때 전송됩니다.

target: 포인터 아래에 있는 시각적 요소입니다.

PointerOutEvent

PointerOutEvent는 포인터가 시각적 요소에서 나갈 때 전송됩니다.

target: 포인터가 있는 시각적 요소입니다.

PointerStationaryEvent

PointerStationaryEvent는 포인터 타입(예: 스타일러스, 손가락)이 운영체제에서 결정한 일정 시간 동안 변경되지 않을 때 전송됩니다.

target: 포인터를 캡처하는 시각적 요소, 또는 포인터 아래에서 선택 가능한 최상위 요소입니다.

PointerCancelEvent

PointerCancelEvent는 운영체제에서 포인터 작업을 취소할 때 전송됩니다.

target: 포인터를 캡처하는 시각적 요소, 또는 포인터 아래에서 선택 가능한 최상위 요소입니다.

예제

다음 코드 샘플은 노란색 상자가 포함된 빨간색 상자가 있는 에디터 창을 생성합니다. 포인터가 시각적 요소 또는 그 자식을 떠날 때 콘솔에 메시지를 출력합니다. 이 예제는 PointerOutEventPointerLeaveEvent의 동작을 시연합니다.

예제가 동작하는 방식을 확인하려면 다음 단계를 따르십시오.

  1. Assets > Scripts > Editor에서 PointerEventsTestWindow.uxml이라는 새 UXML 파일을 생성합니다.
  2. 아래의 UXML 코드를 복사하여 붙여 넣습니다.
  3. Assets > Scripts > Editor에서 PointerEventsTestWindow.cs라는 새 C# 파일을 생성합니다.
  4. 코드 샘플을 복사하여 C# 스크립트에 붙여넣습니다.
  5. 에디터 툴바에서 Window > UI Toolkit > Pointer Events Test Window를 선택합니다.

UXML 코드

<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>

C# 코드


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}");
    }
}

추가 리소스

패널 이벤트
툴팁 이벤트