Module events 

This module defines a stateful set of interaction events driven by the PointerInput stream and the hover state of each Pointer.

Usage

To receive events from this module, you must use an Observer or MessageReader with PointerEvents. The simplest example, registering a callback when an entity is hovered over by a pointer, looks like this:

world.spawn_empty()
    .observe(|event: On<PointerOver>| {
        println!("I am being hovered over");
    });

Observers give us three important properties:

1. They allow for attaching event handlers to specific entities,
2. they allow events to bubble up the entity hierarchy,
3. and they allow events of different types to be called in a specific order.

The order in which interaction events are received is extremely important, and you can read more about it on the docs for the dispatcher system: pointer_events. This system runs in PreUpdate in PickingSystems::Hover. All pointer-event observers resolve during the sync point between pointer_events and update_interactions.

Events Types

The events this module defines fall into a few broad categories:

• Hovering and movement: PointerOver, PointerEnter, PointerMove, PointerLeave, and PointerOut.
• Clicking and pressing: PointerPress, PointerRelease, and PointerClick.
• Dragging and dropping: PointerDragStart, PointerDrag, PointerDragEnd, PointerDragEnter, PointerDragOver, PointerDragDrop, PointerDragLeave.

These events each have a Pointer field, which contains information about the pointer.

Structs

DragEntry

Dragging state.

HoveredEntityAncestors

A cache map containing the ancestry of hovered entities

PickingMessageWriters

A helper system param for accessing the picking event writers.

Pointer

Stores the common data needed for all pointer events.

PointerButtonState

An entry in the cache that drives the pointer_events system, storing additional data about pointer button presses.

PointerCancel

Fires when a pointer is canceled, and its current interaction state is dropped.

PointerClick

Fires when a pointer sends a pointer pressed event followed by a pointer released event, with the same target entity for both events.

PointerDrag

Fires while the target entity is being dragged.

PointerDragDrop

Fires when a pointer drops the dropped entity onto the target entity.

PointerDragEnd

Fires when a pointer is dragging the target entity and a pointer released event is received.

PointerDragEnter

Fires when a pointer dragging the dragged entity enters the target entity

PointerDragLeave

Fires when a pointer dragging the dragged entity leaves the target entity.

PointerDragOver

Fires while the dragged entity is being dragged over the target entity.

PointerDragStart

Fires when the target entity receives a pointer pressed event followed by a pointer move event.

PointerEnter

Fires when a pointer crosses into the bounds of a target entity. Unlike PointerOver, this event bubbles up through a subset of the target entity’s ancestors (traversed via the ChildOf relationship).

PointerLeave

Fires when a pointer crosses out of the bounds of a target entity. Unlike PointerOut, this event bubbles up through a subset of the target entity’s ancestors (traversed via the ChildOf relationship).

PointerMove

Fires while a pointer is moving over the target entity.

PointerOut

Fires when a pointer crosses out of the bounds of a target entity. Unlike PointerLeave, this event bubbles up to all of the target entity’s ancestors (traversed via the ChildOf relationship) without restriction. Refer to pointer_events for more information on how these events are triggered. Refer to PointerTraversal for how Pointer events are propagated.

PointerOver

Fires when a pointer crosses into the bounds of a target entity. Unlike PointerEnter, this event bubbles up to all of the target entity’s ancestors (traversed via the ChildOf relationship) without restriction. Refer to pointer_events for more information on how these events are triggered. Refer to PointerTraversal for how Pointer events are propagated.

PointerPress

Fires when a pointer button is pressed over the target entity.

PointerRelease

Fires when a pointer button is released over the target entity.

PointerScroll

Fires while a pointer is scrolling over the target entity.

PointerState

State for all pointers.

PointerTraversal

A traversal query (i.e. it implements Traversal) intended for use with Pointer events.

PointerTraversalItem

Automatically generated WorldQuery item type for PointerTraversal, returned when iterating over query results.

Traits

PointerEvent

An EntityEvent that contains a Pointer.

Functions

pointer_events

Dispatches interaction events to the target entities.