События указателя

Руководство Unity 2020.3 (LTS)
Создание пользовательских интерфейсов (UI)
Набор инструментов UI
Отправка событий
Захват событий
События указателя

События указателя срабатывают для UI(пользовательский интерфейс) Позволяет пользователю взаимодействовать с вашим приложением. Подробнее
См. в разделе Словарь взаимодействие с указывающим устройством. Подобно событиям мыши, события указателя предоставляют дополнительную информацию об используемом устройстве ввода, например о нажиме пера или угле наклона.

События указателя всегда предшествуют событиям мыши в UI Toolkit.

У событий указателя нет постоянной позиции. У них также нет заданного положения, когда их отпускают с сенсорного устройства.

Некоторые события указателя, такие как события PointerStationaryEvent и PointerCancelEvent, имеют условия, запускаемые операционной системой (ОС) устройство ввода.

Базовым классом для всех событий указателя является PointerEventBase.

Событие	Описание	Стекает вниз	Пузыри вверх	Отменяемый
PointerDownEvent	Отправляется при нажатии указателя.	✔	✔	✔
PointerUpEvent	Отправляется, когда вы отпускаете указатель.	✔	✔	✔
PointerMoveEvent	Отправляется при изменении состояния указателя.	✔	✔	✔
PointerEnterEvent	Отправляется, когда указатель входит в визуальный элемент или один из его потомков.	✔		✔
PointerLeaveEvent	Отправляется, когда указатель покидает визуальный элемент и все его потомки.	✔		✔
PointerOverEvent	Отправляется, когда указатель входит в визуальный элемент.	✔	✔	✔
PointerOutEvent	Отправляется, когда указатель покидает визуальный элемент.	✔	✔	✔
PointerStationaryEvent	Отправляется, когда тип указателя (например, стилус или палец) не меняется в течение заданного периода времени, определяемого операционной системой.	✔	✔	✔
PointerCancelEvent	Отправляется, когда действие указателя отменяется операционной системой.	✔	✔	✔

Уникальные свойства

altitudeAngle: heightAngle содержит угол наклона пера относительно поверхности в радианах. Значение 0 указывает, что игла параллельна поверхности. Значение пи/2 указывает на то, что он перпендикулярен поверхности.

azimuthAngle: azimuthAngle содержит угол наклона стилуса относительно оси X в радианах. Значение 0 указывает, что стилус указывает вдоль оси X устройства.

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	Средняя кнопка

давление: свойство давления возвращает величину давления, прилагаемого в данный момент прикосновением. Если устройство не сообщает о давлении, значение этого свойства равно 1,0f.

radius: свойство radius возвращает оценку радиуса касания. Добавьте radiusVariance, чтобы получить максимальный радиус касания, вычтите его, чтобы получить минимальный радиус касания.

radiusVariance: значение свойства radiusVariance определяет точность радиуса касания. Добавьте это значение к радиусу, чтобы получить максимальный радиус касания, и вычтите его, чтобы получить минимальный радиус касания.

tangentialPressure. Свойство tangentialPressure возвращает значение с плавающей запятой, представляющее давление, приложенное к дополнительному чувствительному к давлению элементу управления на стилусе.

поворот: свойство поворота возвращает вращение пера вокруг своей оси в радианах.

Список событий

В следующем списке указаны имя, описание и цель каждого события в семействе событий. Дополнительную информацию о событии см. в API набора инструментов пользовательского интерфейса.

Событие PointerDown

Событие PointerDownEvent отправляется, когда вы нажимаете указатель внутри визуального элемента.

target: визуальный элемент, который получает захват указателя. В противном случае это самый верхний выбираемый элемент под курсором.

Событие PointerUp

Событие PointerUpEvent срабатывает, когда вы отпускаете указатель внутри визуального элемента.

Когда запускается событие PointerUpEvent, оно также удаляет координаты указателя. Он также очищает кеш указателя, поэтому запись о местоположении указателя не сохраняется.

Событие PointerMove

Событие PointerMoveEvent возникает, когда указатель изменяет свое состояние.

Событие PointerEnter

Событие PointerEnterEvent отправляется, когда указатель входит в визуальный элемент или один из его потомков.

target: визуальный элемент (или один из его потомков), из которого выходит указатель.

Событие PointerLeave

Событие PointerLeaveEvent отправляется, когда указатель покидает визуальный элемент и все его потомки. Например, если визуальный элемент содержит дочерний элемент, то родительский элемент получит это событие, когда указатель больше не находится ни над родительским, ни над дочерним элементом. Родительский элемент не получит PointerLeaveEvent, пока указатель все еще находится над одним из его дочерних элементов, даже если он больше не является самым верхним элементом под указатель. Вместо этого он получит PointerOverEvent.

target: визуальный элемент (или один из его потомков), из которого выходит указатель.

Событие PointerOverEvent

Событие PointerOverEvent отправляется, когда указатель входит в визуальный элемент.

target: визуальный элемент под указателем.

Событие PointerOut

Событие PointerOutEvent отправляется, когда указатель покидает визуальный элемент.

target: визуальный элемент, из которого выходит указатель.

Событие PointerStationary

Событие PointerStationaryEvent отправляется, когда тип указателя (например, пера или пальца) не изменяется в течение заданного периода времени, определяемого операционная система.

target: визуальный элемент, который захватывает указатель, или самый верхний выбираемый элемент под указателем.

Событие PointerCancel

Событие PointerCancelEvent отправляется, когда операционная система отменяет действие указателя.

Примеры

В следующем примере кода создается окно редактора с красным полем, содержащим желтое поле. Он выводит сообщения на консоль, когда указатель покидает визуальный элемент или его дочерний элемент. Он демонстрирует поведение событий PointerOutEvent и PointerLeaveEvent.

Чтобы увидеть пример в действии, сделайте следующее:

В разделе Активы > Скрипты > Редактор создайте новый файл UXML с именем PointerEventsTestWindow.uxml
Скопируйте в него код UXML снизу
В разделе Ресурсы > Сценарии > Редактор создайте новый файл C# с именем PointerEventsTestWindow.cs
Скопируйте пример кода в сценарий C#.
На панели инструментов редактора выберите Окно > Набор инструментов пользовательского интерфейса > Окно проверки событий указателя.

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

Вы можете отблагодарить автора, за перевод документации на русский язык. ₽ Спасибо