Dispatch events

The event system listens for events that come from the operating system or scripts, then uses the EventDispatcher to dispatch those events to visual elements. The event dispatcher determines an appropriate dispatching strategy for each event it sends. Once determined, the dispatcher executes the strategy.

Visual elements implement default behaviors for several events. This involves the creation and execution of additional events. For example, a PointerMoveEvent can generate an additional PointerEnterEvent and a PointerLeaveEvent. These events enter a queue and process after the current event. For example, the PointerMoveEvent finishes processing before the PointerEnterEvent and PointerLeaveEvent events.

事件类型的分发行为

Each event type has its own dispatch behavior. The behavior of each event type breaks down into two stages:

• Trickles down: Events sent to elements during the trickle-down phase.
• 冒泡：在冒泡阶段发送到元素的事件。

有关每种事件类型的分发行为的列表，请参阅事件参考页面 。

事件传播

事件分发程序选择事件目标后，会计算事件的传播路径。传播路径是接收事件的视觉元素的有序列表。传播路径按以下顺序发生：

1. 路径从视觉元素树的根部开始，并朝着目标下降。此阶段称为涓滴 (trickle-down) 阶段。
2. 事件目标接收事件。
3. 然后事件沿着树上升到根。此阶段称为冒泡 (bubble-up) 阶段 。

大多数事件类型将沿着传播路径发送到所有元素。某些事件类型跳过冒泡阶段，某些事件类型仅发送到事件目标。

如果元素被隐藏或禁用，它将不会接收事件。事件仍会传播到被隐藏或禁用的元素的祖先和后代。

事件目标

在事件沿着传播路径行进时，Event.currentTarget 更新为当前正在处理该事件的元素。在事件回调函数中，有两个属性记录了分发行为：

• EventBase.currentTarget is the visual element on which the callback was registered.
• EventBase.target is the element where the event occurs, for example, the element directly under the pointer.

The target of an event depends on the event type. For pointer events, the target is most commonly the topmost pickable element, directly under the pointer. For keyboard events, the target is the element that has focus.

UI Toolkit events have a target property that contains a reference to the element where the event occurred. For most events that originate from the operating system, the dispatch process finds the event target automatically.

目标元素存储在 EventBase.target 中并且在分发过程中不会改变。属性 Event.currentTarget 会更新为当前正在处理该事件的视觉元素。

拾取模式和自定义形状

Most pointer events use the picking mode to decide their target. The VisualElement class has a pickingMode property that supports the following values:

• PickingMode.Position (default): performs picking based on the position rectangle.
• PickingMode.Ignore: prevents picking as the result of a pointer event.

You can override the VisualElement.ContainsPoint() method to perform custom intersection logic.

其他资源

• Handle event callbacks and value changes
• Synthesize and send events
• Events reference