forestia/bevy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d0ed58780b
bevy/crates/bevy_window/src/event.rs
Joona Aalto 38c3423693
Event Split: Event, EntityEvent, and BufferedEvent (#19647) 
# Objective

Closes #19564.

The current `Event` trait looks like this:

```rust
pub trait Event: Send + Sync + 'static {
    type Traversal: Traversal<Self>;
    const AUTO_PROPAGATE: bool = false;
    
    fn register_component_id(world: &mut World) -> ComponentId { ... }
    fn component_id(world: &World) -> Option<ComponentId> { ... }
}
```

The `Event` trait is used by both buffered events
(`EventReader`/`EventWriter`) and observer events. If they are observer
events, they can optionally be targeted at specific `Entity`s or
`ComponentId`s, and can even be propagated to other entities.

However, there has long been a desire to split the trait semantically
for a variety of reasons, see #14843, #14272, and #16031 for discussion.
Some reasons include:

- It's very uncommon to use a single event type as both a buffered event
and targeted observer event. They are used differently and tend to have
distinct semantics.
- A common footgun is using buffered events with observers or event
readers with observer events, as there is no type-level error that
prevents this kind of misuse.
- #19440 made `Trigger::target` return an `Option<Entity>`. This
*seriously* hurts ergonomics for the general case of entity observers,
as you need to `.unwrap()` each time. If we could statically determine
whether the event is expected to have an entity target, this would be
unnecessary.

There's really two main ways that we can categorize events: push vs.
pull (i.e. "observer event" vs. "buffered event") and global vs.
targeted:

|              | Push            | Pull                        |
| ------------ | --------------- | --------------------------- |
| **Global**   | Global observer | `EventReader`/`EventWriter` |
| **Targeted** | Entity observer | -                           |

There are many ways to approach this, each with their tradeoffs.
Ultimately, we kind of want to split events both ways:

- A type-level distinction between observer events and buffered events,
to prevent people from using the wrong kind of event in APIs
- A statically designated entity target for observer events to avoid
accidentally using untargeted events for targeted APIs

This PR achieves these goals by splitting event traits into `Event`,
`EntityEvent`, and `BufferedEvent`, with `Event` being the shared trait
implemented by all events.

## `Event`, `EntityEvent`, and `BufferedEvent`

`Event` is now a very simple trait shared by all events.

```rust
pub trait Event: Send + Sync + 'static {
    // Required for observer APIs
    fn register_component_id(world: &mut World) -> ComponentId { ... }
    fn component_id(world: &World) -> Option<ComponentId> { ... }
}
```

You can call `trigger` for *any* event, and use a global observer for
listening to the event.

```rust
#[derive(Event)]
struct Speak {
    message: String,
}

// ...

app.add_observer(|trigger: On<Speak>| {
    println!("{}", trigger.message);
});

// ...

commands.trigger(Speak {
    message: "Y'all like these reworked events?".to_string(),
});
```

To allow an event to be targeted at entities and even propagated
further, you can additionally implement the `EntityEvent` trait:

```rust
pub trait EntityEvent: Event {
    type Traversal: Traversal<Self>;
    const AUTO_PROPAGATE: bool = false;
}
```

This lets you call `trigger_targets`, and to use targeted observer APIs
like `EntityCommands::observe`:

```rust
#[derive(Event, EntityEvent)]
#[entity_event(traversal = &'static ChildOf, auto_propagate)]
struct Damage {
    amount: f32,
}

// ...

let enemy = commands.spawn((Enemy, Health(100.0))).id();

// Spawn some armor as a child of the enemy entity.
// When the armor takes damage, it will bubble the event up to the enemy.
let armor_piece = commands
    .spawn((ArmorPiece, Health(25.0), ChildOf(enemy)))
    .observe(|trigger: On<Damage>, mut query: Query<&mut Health>| {
        // Note: `On::target` only exists because this is an `EntityEvent`.
        let mut health = query.get(trigger.target()).unwrap();
        health.0 -= trigger.amount();
    });

commands.trigger_targets(Damage { amount: 10.0 }, armor_piece);
```

> [!NOTE]
> You *can* still also trigger an `EntityEvent` without targets using
`trigger`. We probably *could* make this an either-or thing, but I'm not
sure that's actually desirable.

To allow an event to be used with the buffered API, you can implement
`BufferedEvent`:

```rust
pub trait BufferedEvent: Event {}
```

The event can then be used with `EventReader`/`EventWriter`:

```rust
#[derive(Event, BufferedEvent)]
struct Message(String);

fn write_hello(mut writer: EventWriter<Message>) {
    writer.write(Message("I hope these examples are alright".to_string()));
}

fn read_messages(mut reader: EventReader<Message>) {
    // Process all buffered events of type `Message`.
    for Message(message) in reader.read() {
        println!("{message}");
    }
}
```

In summary:

- Need a basic event you can trigger and observe? Derive `Event`!
- Need the event to be targeted at an entity? Derive `EntityEvent`!
- Need the event to be buffered and support the
`EventReader`/`EventWriter` API? Derive `BufferedEvent`!

## Alternatives

I'll now cover some of the alternative approaches I have considered and
briefly explored. I made this section collapsible since it ended up
being quite long :P

<details>

<summary>Expand this to see alternatives</summary>

### 1. Unified `Event` Trait

One option is not to have *three* separate traits (`Event`,
`EntityEvent`, `BufferedEvent`), and to instead just use associated
constants on `Event` to determine whether an event supports targeting
and buffering or not:

```rust
pub trait Event: Send + Sync + 'static {
    type Traversal: Traversal<Self>;
    const AUTO_PROPAGATE: bool = false;
    const TARGETED: bool = false;
    const BUFFERED: bool = false;
    
    fn register_component_id(world: &mut World) -> ComponentId { ... }
    fn component_id(world: &World) -> Option<ComponentId> { ... }
}
```

Methods can then use bounds like `where E: Event<TARGETED = true>` or
`where E: Event<BUFFERED = true>` to limit APIs to specific kinds of
events.

This would keep everything under one `Event` trait, but I don't think
it's necessarily a good idea. It makes APIs harder to read, and docs
can't easily refer to specific types of events. You can also create
weird invariants: what if you specify `TARGETED = false`, but have
`Traversal` and/or `AUTO_PROPAGATE` enabled?

### 2. `Event` and `Trigger`

Another option is to only split the traits between buffered events and
observer events, since that is the main thing people have been asking
for, and they have the largest API difference.

If we did this, I think we would need to make the terms *clearly*
separate. We can't really use `Event` and `BufferedEvent` as the names,
since it would be strange that `BufferedEvent` doesn't implement
`Event`. Something like `ObserverEvent` and `BufferedEvent` could work,
but it'd be more verbose.

For this approach, I would instead keep `Event` for the current
`EventReader`/`EventWriter` API, and call the observer event a
`Trigger`, since the "trigger" terminology is already used in the
observer context within Bevy (both as a noun and a verb). This is also
what a long [bikeshed on
Discord](https://discord.com/channels/691052431525675048/749335865876021248/1298057661878898791)
seemed to land on at the end of last year.

```rust
// For `EventReader`/`EventWriter`
pub trait Event: Send + Sync + 'static {}

// For observers
pub trait Trigger: Send + Sync + 'static {
    type Traversal: Traversal<Self>;
    const AUTO_PROPAGATE: bool = false;
    const TARGETED: bool = false;
    
    fn register_component_id(world: &mut World) -> ComponentId { ... }
    fn component_id(world: &World) -> Option<ComponentId> { ... }
}
```

The problem is that "event" is just a really good term for something
that "happens". Observers are rapidly becoming the more prominent API,
so it'd be weird to give them the `Trigger` name and leave the good
`Event` name for the less common API.

So, even though a split like this seems neat on the surface, I think it
ultimately wouldn't really work. We want to keep the `Event` name for
observer events, and there is no good alternative for the buffered
variant. (`Message` was suggested, but saying stuff like "sends a
collision message" is weird.)

### 3. `GlobalEvent` + `TargetedEvent`

What if instead of focusing on the buffered vs. observed split, we
*only* make a distinction between global and targeted events?

```rust
// A shared event trait to allow global observers to work
pub trait Event: Send + Sync + 'static {
    fn register_component_id(world: &mut World) -> ComponentId { ... }
    fn component_id(world: &World) -> Option<ComponentId> { ... }
}

// For buffered events and non-targeted observer events
pub trait GlobalEvent: Event {}

// For targeted observer events
pub trait TargetedEvent: Event {
    type Traversal: Traversal<Self>;
    const AUTO_PROPAGATE: bool = false;
}
```

This is actually the first approach I implemented, and it has the neat
characteristic that you can only use non-targeted APIs like `trigger`
with a `GlobalEvent` and targeted APIs like `trigger_targets` with a
`TargetedEvent`. You have full control over whether the entity should or
should not have a target, as they are fully distinct at the type-level.

However, there's a few problems:

- There is no type-level indication of whether a `GlobalEvent` supports
buffered events or just non-targeted observer events
- An `Event` on its own does literally nothing, it's just a shared trait
required to make global observers accept both non-targeted and targeted
events
- If an event is both a `GlobalEvent` and `TargetedEvent`, global
observers again have ambiguity on whether an event has a target or not,
undermining some of the benefits
- The names are not ideal

### 4. `Event` and `EntityEvent`

We can fix some of the problems of Alternative 3 by accepting that
targeted events can also be used in non-targeted contexts, and simply
having the `Event` and `EntityEvent` traits:

```rust
// For buffered events and non-targeted observer events
pub trait Event: Send + Sync + 'static {
    fn register_component_id(world: &mut World) -> ComponentId { ... }
    fn component_id(world: &World) -> Option<ComponentId> { ... }
}

// For targeted observer events
pub trait EntityEvent: Event {
    type Traversal: Traversal<Self>;
    const AUTO_PROPAGATE: bool = false;
}
```

This is essentially identical to this PR, just without a dedicated
`BufferedEvent`. The remaining major "problem" is that there is still
zero type-level indication of whether an `Event` event *actually*
supports the buffered API. This leads us to the solution proposed in
this PR, using `Event`, `EntityEvent`, and `BufferedEvent`.

</details>

## Conclusion

The `Event` + `EntityEvent` + `BufferedEvent` split proposed in this PR
aims to solve all the common problems with Bevy's current event model
while keeping the "weirdness" factor minimal. It splits in terms of both
the push vs. pull *and* global vs. targeted aspects, while maintaining a
shared concept for an "event".

### Why I Like This

- The term "event" remains as a single concept for all the different
kinds of events in Bevy.
- Despite all event types being "events", they use fundamentally
different APIs. Instead of assuming that you can use an event type with
any pattern (when only one is typically supported), you explicitly opt
in to each one with dedicated traits.
- Using separate traits for each type of event helps with documentation
and clearer function signatures.
- I can safely make assumptions on expected usage.
- If I see that an event is an `EntityEvent`, I can assume that I can
use `observe` on it and get targeted events.
- If I see that an event is a `BufferedEvent`, I can assume that I can
use `EventReader` to read events.
- If I see both `EntityEvent` and `BufferedEvent`, I can assume that
both APIs are supported.

In summary: This allows for a unified concept for events, while limiting
the different ways to use them with opt-in traits. No more guess-work
involved when using APIs.

### Problems?

- Because `BufferedEvent` implements `Event` (for more consistent
semantics etc.), you can still use all buffered events for non-targeted
observers. I think this is fine/good. The important part is that if you
see that an event implements `BufferedEvent`, you know that the
`EventReader`/`EventWriter` API should be supported. Whether it *also*
supports other APIs is secondary.
- I currently only support `trigger_targets` for an `EntityEvent`.
However, you can technically target components too, without targeting
any entities. I consider that such a niche and advanced use case that
it's not a huge problem to only support it for `EntityEvent`s, but we
could also split `trigger_targets` into `trigger_entities` and
`trigger_components` if we wanted to (or implement components as
entities :P).
- You can still trigger an `EntityEvent` *without* targets. I consider
this correct, since `Event` implements the non-targeted behavior, and
it'd be weird if implementing another trait *removed* behavior. However,
it does mean that global observers for entity events can technically
return `Entity::PLACEHOLDER` again (since I got rid of the
`Option<Entity>` added in #19440 for ergonomics). I think that's enough
of an edge case that it's not a huge problem, but it is worth keeping in
mind.
- ~~Deriving both `EntityEvent` and `BufferedEvent` for the same type
currently duplicates the `Event` implementation, so you instead need to
manually implement one of them.~~ Changed to always requiring `Event` to
be derived.

## Related Work

There are plans to implement multi-event support for observers,
especially for UI contexts. [Cart's
example](https://github.com/bevyengine/bevy/issues/14649#issuecomment-2960402508)
API looked like this:

```rust
// Truncated for brevity
trigger: Trigger<(
    OnAdd<Pressed>,
    OnRemove<Pressed>,
    OnAdd<InteractionDisabled>,
    OnRemove<InteractionDisabled>,
    OnInsert<Hovered>,
)>,
```

I believe this shouldn't be in conflict with this PR. If anything, this
PR might *help* achieve the multi-event pattern for entity observers
with fewer footguns: by statically enforcing that all of these events
are `EntityEvent`s in the context of `EntityCommands::observe`, we can
avoid misuse or weird cases where *some* events inside the trigger are
targeted while others are not.
2025-06-15 16:46:34 +00:00

675 lines
21 KiB
Rust
Raw Blame History

use alloc::string::String;
use bevy_ecs::{
entity::Entity,
event::{BufferedEvent, Event},
};
use bevy_input::{
gestures::*,
keyboard::{KeyboardFocusLost, KeyboardInput},
mouse::{MouseButtonInput, MouseMotion, MouseWheel},
touch::TouchInput,
};
use bevy_math::{IVec2, Vec2};
#[cfg(feature = "std")]
use std::path::PathBuf;
#[cfg(not(feature = "std"))]
use alloc::string::String as PathBuf;
#[cfg(feature = "bevy_reflect")]
use bevy_reflect::Reflect;
#[cfg(feature = "serialize")]
use bevy_reflect::{ReflectDeserialize, ReflectSerialize};
use crate::WindowTheme;
/// A window event that is sent whenever a window's logical size has changed.
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct WindowResized {
/// Window that has changed.
pub window: Entity,
/// The new logical width of the window.
pub width: f32,
/// The new logical height of the window.
pub height: f32,
}
/// An event that indicates all of the application's windows should be redrawn,
/// even if their control flow is set to `Wait` and there have been no window events.
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct RequestRedraw;
/// An event that is sent whenever a new window is created.
///
/// To create a new window, spawn an entity with a [`crate::Window`] on it.
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct WindowCreated {
/// Window that has been created.
pub window: Entity,
}
/// An event that is sent whenever the operating systems requests that a window
/// be closed. This will be sent when the close button of the window is pressed.
///
/// If the default [`WindowPlugin`] is used, these events are handled
/// by closing the corresponding [`Window`].
/// To disable this behavior, set `close_when_requested` on the [`WindowPlugin`]
/// to `false`.
///
/// [`WindowPlugin`]: crate::WindowPlugin
/// [`Window`]: crate::Window
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct WindowCloseRequested {
/// Window to close.
pub window: Entity,
}
/// An event that is sent whenever a window is closed. This will be sent when
/// the window entity loses its [`Window`](crate::window::Window) component or is despawned.
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct WindowClosed {
/// Window that has been closed.
///
/// Note that this entity probably no longer exists
/// by the time this event is received.
pub window: Entity,
}
/// An event that is sent whenever a window is closing. This will be sent when
/// after a [`WindowCloseRequested`] event is received and the window is in the process of closing.
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct WindowClosing {
/// Window that has been requested to close and is the process of closing.
pub window: Entity,
}
/// An event that is sent whenever a window is destroyed by the underlying window system.
///
/// Note that if your application only has a single window, this event may be your last chance to
/// persist state before the application terminates.
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct WindowDestroyed {
/// Window that has been destroyed.
///
/// Note that this entity probably no longer exists
/// by the time this event is received.
pub window: Entity,
}
/// An event reporting that the mouse cursor has moved inside a window.
///
/// The event is sent only if the cursor is over one of the application's windows.
/// It is the translated version of [`WindowEvent::CursorMoved`] from the `winit` crate with the addition of `delta`.
///
/// Not to be confused with the `MouseMotion` event from `bevy_input`.
///
/// Because the range of data is limited by the window area and it may have been transformed by the OS to implement certain effects like acceleration,
/// you should not use it for non-cursor-like behavior such as 3D camera control. Please see `MouseMotion` instead.
///
/// [`WindowEvent::CursorMoved`]: https://docs.rs/winit/latest/winit/event/enum.WindowEvent.html#variant.CursorMoved
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct CursorMoved {
/// Window that the cursor moved inside.
pub window: Entity,
/// The cursor position in logical pixels.
pub position: Vec2,
/// The change in the position of the cursor since the last event was sent.
/// This value is `None` if the cursor was outside the window area during the last frame.
// Because the range of this data is limited by the display area and it may have been
// transformed by the OS to implement effects such as cursor acceleration, it should
// not be used to implement non-cursor-like interactions such as 3D camera control.
pub delta: Option<Vec2>,
}
/// An event that is sent whenever the user's cursor enters a window.
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct CursorEntered {
/// Window that the cursor entered.
pub window: Entity,
}
/// An event that is sent whenever the user's cursor leaves a window.
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct CursorLeft {
/// Window that the cursor left.
pub window: Entity,
}
/// An Input Method Editor event.
///
/// This event is the translated version of the `WindowEvent::Ime` from the `winit` crate.
///
/// It is only sent if IME was enabled on the window with [`Window::ime_enabled`](crate::window::Window::ime_enabled).
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub enum Ime {
/// Notifies when a new composing text should be set at the cursor position.
Preedit {
/// Window that received the event.
window: Entity,
/// Current value.
value: String,
/// Cursor begin and end position.
///
/// `None` indicated the cursor should be hidden
cursor: Option<(usize, usize)>,
},
/// Notifies when text should be inserted into the editor widget.
Commit {
/// Window that received the event.
window: Entity,
/// Input string
value: String,
},
/// Notifies when the IME was enabled.
///
/// After this event, you will receive events `Ime::Preedit` and `Ime::Commit`.
Enabled {
/// Window that received the event.
window: Entity,
},
/// Notifies when the IME was disabled.
Disabled {
/// Window that received the event.
window: Entity,
},
}
/// An event that indicates a window has received or lost focus.
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct WindowFocused {
/// Window that changed focus.
pub window: Entity,
/// Whether it was focused (true) or lost focused (false).
pub focused: bool,
}
/// The window has been occluded (completely hidden from view).
///
/// This is different to window visibility as it depends on
/// whether the window is closed, minimized, set invisible,
/// or fully occluded by another window.
///
/// It is the translated version of [`WindowEvent::Occluded`] from the `winit` crate.
///
/// [`WindowEvent::Occluded`]: https://docs.rs/winit/latest/winit/event/enum.WindowEvent.html#variant.Occluded
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct WindowOccluded {
/// Window that changed occluded state.
pub window: Entity,
/// Whether it was occluded (true) or not occluded (false).
pub occluded: bool,
}
/// An event that indicates a window's scale factor has changed.
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct WindowScaleFactorChanged {
/// Window that had its scale factor changed.
pub window: Entity,
/// The new scale factor.
pub scale_factor: f64,
}
/// An event that indicates a window's OS-reported scale factor has changed.
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct WindowBackendScaleFactorChanged {
/// Window that had its scale factor changed by the backend.
pub window: Entity,
/// The new scale factor.
pub scale_factor: f64,
}
/// Events related to files being dragged and dropped on a window.
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub enum FileDragAndDrop {
/// File is being dropped into a window.
DroppedFile {
/// Window the file was dropped into.
window: Entity,
/// Path to the file that was dropped in.
path_buf: PathBuf,
},
/// File is currently being hovered over a window.
HoveredFile {
/// Window a file is possibly going to be dropped into.
window: Entity,
/// Path to the file that might be dropped in.
path_buf: PathBuf,
},
/// File hovering was canceled.
HoveredFileCanceled {
/// Window that had a canceled file drop.
window: Entity,
},
}
/// An event that is sent when a window is repositioned in physical pixels.
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct WindowMoved {
/// Window that moved.
pub window: Entity,
/// Where the window moved to in physical pixels.
pub position: IVec2,
}
/// An event sent when the system theme changes for a window.
///
/// This event is only sent when the window is relying on the system theme to control its appearance.
/// i.e. It is only sent when [`Window::window_theme`](crate::window::Window::window_theme) is `None` and the system theme changes.
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub struct WindowThemeChanged {
/// Window for which the system theme has changed.
pub window: Entity,
/// The new system theme.
pub theme: WindowTheme,
}
/// Application lifetime events
#[derive(Event, BufferedEvent, Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
pub enum AppLifecycle {
/// The application is not started yet.
Idle,
/// The application is running.
Running,
/// The application is going to be suspended.
/// Applications have one frame to react to this event before being paused in the background.
WillSuspend,
/// The application was suspended.
Suspended,
/// The application is going to be resumed.
/// Applications have one extra frame to react to this event before being fully resumed.
WillResume,
}
impl AppLifecycle {
/// Return `true` if the app can be updated.
#[inline]
pub fn is_active(&self) -> bool {
match self {
Self::Idle | Self::Suspended => false,
Self::Running | Self::WillSuspend | Self::WillResume => true,
}
}
}
/// Wraps all `bevy_window` and `bevy_input` events in a common enum.
///
/// Read these events with `EventReader<WindowEvent>` if you need to
/// access window events in the order they were received from the
/// operating system. Otherwise, the event types are individually
/// readable with `EventReader<E>` (e.g. `EventReader<KeyboardInput>`).
#[derive(Event, BufferedEvent, Debug, Clone, PartialEq)]
#[cfg_attr(
feature = "bevy_reflect",
derive(Reflect),
reflect(Debug, PartialEq, Clone)
)]
#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(
all(feature = "serialize", feature = "bevy_reflect"),
reflect(Serialize, Deserialize)
)]
#[expect(missing_docs, reason = "Not all docs are written yet, see #3492.")]
pub enum WindowEvent {
AppLifecycle(AppLifecycle),
CursorEntered(CursorEntered),
CursorLeft(CursorLeft),
CursorMoved(CursorMoved),
FileDragAndDrop(FileDragAndDrop),
Ime(Ime),
RequestRedraw(RequestRedraw),
WindowBackendScaleFactorChanged(WindowBackendScaleFactorChanged),
WindowCloseRequested(WindowCloseRequested),
WindowCreated(WindowCreated),
WindowDestroyed(WindowDestroyed),
WindowFocused(WindowFocused),
WindowMoved(WindowMoved),
WindowOccluded(WindowOccluded),
WindowResized(WindowResized),
WindowScaleFactorChanged(WindowScaleFactorChanged),
WindowThemeChanged(WindowThemeChanged),
MouseButtonInput(MouseButtonInput),
MouseMotion(MouseMotion),
MouseWheel(MouseWheel),
PinchGesture(PinchGesture),
RotationGesture(RotationGesture),
DoubleTapGesture(DoubleTapGesture),
PanGesture(PanGesture),
TouchInput(TouchInput),
KeyboardInput(KeyboardInput),
KeyboardFocusLost(KeyboardFocusLost),
}
impl From<AppLifecycle> for WindowEvent {
fn from(e: AppLifecycle) -> Self {
Self::AppLifecycle(e)
}
}
impl From<CursorEntered> for WindowEvent {
fn from(e: CursorEntered) -> Self {
Self::CursorEntered(e)
}
}
impl From<CursorLeft> for WindowEvent {
fn from(e: CursorLeft) -> Self {
Self::CursorLeft(e)
}
}
impl From<CursorMoved> for WindowEvent {
fn from(e: CursorMoved) -> Self {
Self::CursorMoved(e)
}
}
impl From<FileDragAndDrop> for WindowEvent {
fn from(e: FileDragAndDrop) -> Self {
Self::FileDragAndDrop(e)
}
}
impl From<Ime> for WindowEvent {
fn from(e: Ime) -> Self {
Self::Ime(e)
}
}
impl From<RequestRedraw> for WindowEvent {
fn from(e: RequestRedraw) -> Self {
Self::RequestRedraw(e)
}
}
impl From<WindowBackendScaleFactorChanged> for WindowEvent {
fn from(e: WindowBackendScaleFactorChanged) -> Self {
Self::WindowBackendScaleFactorChanged(e)
}
}
impl From<WindowCloseRequested> for WindowEvent {
fn from(e: WindowCloseRequested) -> Self {
Self::WindowCloseRequested(e)
}
}
impl From<WindowCreated> for WindowEvent {
fn from(e: WindowCreated) -> Self {
Self::WindowCreated(e)
}
}
impl From<WindowDestroyed> for WindowEvent {
fn from(e: WindowDestroyed) -> Self {
Self::WindowDestroyed(e)
}
}
impl From<WindowFocused> for WindowEvent {
fn from(e: WindowFocused) -> Self {
Self::WindowFocused(e)
}
}
impl From<WindowMoved> for WindowEvent {
fn from(e: WindowMoved) -> Self {
Self::WindowMoved(e)
}
}
impl From<WindowOccluded> for WindowEvent {
fn from(e: WindowOccluded) -> Self {
Self::WindowOccluded(e)
}
}
impl From<WindowResized> for WindowEvent {
fn from(e: WindowResized) -> Self {
Self::WindowResized(e)
}
}
impl From<WindowScaleFactorChanged> for WindowEvent {
fn from(e: WindowScaleFactorChanged) -> Self {
Self::WindowScaleFactorChanged(e)
}
}
impl From<WindowThemeChanged> for WindowEvent {
fn from(e: WindowThemeChanged) -> Self {
Self::WindowThemeChanged(e)
}
}
impl From<MouseButtonInput> for WindowEvent {
fn from(e: MouseButtonInput) -> Self {
Self::MouseButtonInput(e)
}
}
impl From<MouseMotion> for WindowEvent {
fn from(e: MouseMotion) -> Self {
Self::MouseMotion(e)
}
}
impl From<MouseWheel> for WindowEvent {
fn from(e: MouseWheel) -> Self {
Self::MouseWheel(e)
}
}
impl From<PinchGesture> for WindowEvent {
fn from(e: PinchGesture) -> Self {
Self::PinchGesture(e)
}
}
impl From<RotationGesture> for WindowEvent {
fn from(e: RotationGesture) -> Self {
Self::RotationGesture(e)
}
}
impl From<DoubleTapGesture> for WindowEvent {
fn from(e: DoubleTapGesture) -> Self {
Self::DoubleTapGesture(e)
}
}
impl From<PanGesture> for WindowEvent {
fn from(e: PanGesture) -> Self {
Self::PanGesture(e)
}
}
impl From<TouchInput> for WindowEvent {
fn from(e: TouchInput) -> Self {
Self::TouchInput(e)
}
}
impl From<KeyboardInput> for WindowEvent {
fn from(e: KeyboardInput) -> Self {
Self::KeyboardInput(e)
}
}
impl From<KeyboardFocusLost> for WindowEvent {
fn from(e: KeyboardFocusLost) -> Self {
Self::KeyboardFocusLost(e)
}
}
Reference in New Issue View Git Blame Copy Permalink