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 The simplest example, registering a callback when an entity is hovered over by a pointer, looks like this:

world.spawn_empty()
    .observe(|trigger: Trigger<Pointer<Over>>| {
        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 PickSet::Focus. 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: Over, Move, and Out.
• Clicking and pressing: Down, Up, and Click.
• Dragging and dropping: DragStart, Drag, DragEnd, DragEnter, DragOver, DragDrop, DragLeave.

When received by an observer, these events will always be wrapped by the Pointer type, which contains general metadata about the pointer and it’s location.

Structs

Cancel

Fires when a pointer is canceled, and it’s current interaction state is dropped.

Click

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

Down

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

Drag

Fires while the target entity is being dragged.

DragDrop

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

DragEnd

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

DragEnter

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

DragEntry

Dragging state.

DragLeave

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

DragOver

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

DragStart

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

Move

Fires while a pointer is moving over the target entity.

Out

Fires when a the pointer crosses out of the bounds of the target entity.

Over

Fires when a the pointer crosses into the bounds of the target entity.

PickingEventWriters

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.

PointerState

State for all pointers.

Up

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

Functions

pointer_events

Dispatches interaction events to the target entities.