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

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

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

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

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

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

В следующей таблице описаны события указателя и фазы их распространения:

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

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

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

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

button: Содержит целое число, идентифицирующее кнопку мыши, нажатую для запуска события. В следующей таблице перечислены целое число и соответствующая кнопка мыши:

Цифры	Кнопка
0	Левая кнопка
1	Правая кнопка
2	Средняя кнопка

clickCount: Содержит информацию о количестве нажатий кнопки.

deltaPosition: Содержит разницу между позицией указателя во время предыдущего события мыши и его позицией во время текущего события мыши.

deltaTime: Содержит количество времени, которое прошло из-за последнего записанного изменения значений указателя, в секундах.

localPosition: Возвращает положение указателя относительно целевого визуального элемента.

modifiers: Возвращает клавишу модификатора, нажатую в данный момент. Некоторые примеры модификаторов: Shift, Ctrlили Alt. Для получения дополнительных сведений см. раздел Клавиши модификатора документации MDN.

pointerId: Возвращает целое число, идентифицирующее указатель, который отправляет событие.

pointerType: Возвращает строку, определяющую тип указателя, создающего событие.

position: Возвращает позицию указателя в системе координат экрана или мира.

pressedButtons: Возвращает целое число, которое идентифицирует, какая комбинация кнопок мыши нажата в данный момент.

Число представляет собой сумму целых значений отдельных кнопок (см. таблицу ниже). Например, удержание правой кнопки мыши и средней кнопки мыши одновременно приведет к тому, что pressedButtons будет иметь значение 6.

Цифры	Кнопка
1	Левая кнопка
2	Правая кнопка
4	Средняя кнопка

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

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

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

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

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

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

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

PointerDownEvent

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

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

PointerUpEvent

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

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

PointerMoveEvent

PointerMoveEvent происходит, когда указатель меняет состояние.

PointerEnterEvent

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

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

PointerLeaveEvent

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

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

PointerOverEvent

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

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

PointerOutEvent

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

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

PointerStationaryEvent

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

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

PointerCancelEvent

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

Примеры

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

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

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

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

Дополнительные ресурсы

Создание перетаскивания UI