From 48fe2a6e2157f79a275eb26b6aa14deafeed85eb Mon Sep 17 00:00:00 2001 From: Alice Cecile Date: Tue, 24 Dec 2024 01:22:13 -0500 Subject: [PATCH] Rename "focus" in `bevy_picking` to "hover" (#16872) # Objective With the introduction of bevy_input_focus, the uses of "focus" in bevy_picking are quite confusing and make searching hard. Users will intuitively think these concepts are related, but they actually aren't. ## Solution Rename / rephrase all uses of "focus" in bevy_picking to refer to "hover", since this is ultimately related to creating the `HoverMap`. ## Migration Guide Various terms related to "focus" in `bevy_picking` have been renamed to refer to "hover" to avoid confusion with `bevy_input_focus`. In particular: - The `update_focus` system has been renamed to `generate_hovermap` - `PickSet::Focus` and `PostFocus` have been renamed to `Hover` and `PostHover` - The `bevy_picking::focus` module has been renamed to `bevy_picking::hover` - The `is_focus_enabled` field on `PickingPlugin` has been renamed to `is_hover_enabled` - The `focus_should_run` run condition has been renamed to `hover_should_run` --- crates/bevy_picking/src/events.rs | 8 ++-- .../bevy_picking/src/{focus.rs => hover.rs} | 2 +- crates/bevy_picking/src/lib.rs | 44 +++++++++---------- examples/testbed/ui.rs | 2 +- examples/ui/scroll.rs | 2 +- 5 files changed, 29 insertions(+), 29 deletions(-) rename crates/bevy_picking/src/{focus.rs => hover.rs} (99%) diff --git a/crates/bevy_picking/src/events.rs b/crates/bevy_picking/src/events.rs index 41dfa8c4b05ed..3ccabd0a9bc5b 100644 --- a/crates/bevy_picking/src/events.rs +++ b/crates/bevy_picking/src/events.rs @@ -23,9 +23,9 @@ //! //! 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`](bevy_app::PreUpdate) in [`PickSet::Focus`](crate::PickSet::Focus). All pointer-event +//! [`PreUpdate`](bevy_app::PreUpdate) in [`PickSet::Hover`](crate::PickSet::Hover). All pointer-event //! observers resolve during the sync point between [`pointer_events`] and -//! [`update_interactions`](crate::focus::update_interactions). +//! [`update_interactions`](crate::hover::update_interactions). //! //! # Events Types //! @@ -49,7 +49,7 @@ use bevy_window::Window; use crate::{ backend::{prelude::PointerLocation, HitData}, - focus::{HoverMap, PreviousHoverMap}, + hover::{HoverMap, PreviousHoverMap}, pointer::{ Location, PointerAction, PointerButton, PointerId, PointerInput, PointerMap, PressDirection, }, @@ -385,7 +385,7 @@ pub struct PickingEventWriters<'w> { /// receive [`Out`] and then entity B will receive [`Over`]. No entity will ever /// receive both an [`Over`] and and a [`Out`] event during the same frame. /// -/// When we account for event bubbling, this is no longer true. When focus shifts +/// When we account for event bubbling, this is no longer true. When the hovering focus shifts /// between children, parent entities may receive redundant [`Out`] → [`Over`] pairs. /// In the context of UI, this is especially problematic. Additional hierarchy-aware /// events will be added in a future release. diff --git a/crates/bevy_picking/src/focus.rs b/crates/bevy_picking/src/hover.rs similarity index 99% rename from crates/bevy_picking/src/focus.rs rename to crates/bevy_picking/src/hover.rs index e730e41ce7d45..bc91ee79f7a35 100644 --- a/crates/bevy_picking/src/focus.rs +++ b/crates/bevy_picking/src/hover.rs @@ -62,7 +62,7 @@ pub struct PreviousHoverMap(pub HashMap>); /// Coalesces all data from inputs and backends to generate a map of the currently hovered entities. /// This is the final focusing step to determine which entity the pointer is hovering over. -pub fn update_focus( +pub fn generate_hovermap( // Inputs picking_behavior: Query<&PickingBehavior>, pointers: Query<&PointerId>, diff --git a/crates/bevy_picking/src/lib.rs b/crates/bevy_picking/src/lib.rs index 21f54e27ad9b1..03e0269fb50db 100644 --- a/crates/bevy_picking/src/lib.rs +++ b/crates/bevy_picking/src/lib.rs @@ -128,12 +128,12 @@ //! Bevy provides some backends out of the box, but you can even write your own. It's been //! made as easy as possible intentionally; the `bevy_mod_raycast` backend is 50 lines of code. //! -//! #### Focus ([`focus`]) +//! #### Hover ([`hover`]) //! //! The next step is to use the data from the backends, combine and sort the results, and determine -//! what each cursor is hovering over, producing a [`HoverMap`](`crate::focus::HoverMap`). Note that +//! what each cursor is hovering over, producing a [`HoverMap`](`crate::hover::HoverMap`). Note that //! just because a pointer is over an entity, it is not necessarily *hovering* that entity. Although -//! multiple backends may be reporting that a pointer is hitting an entity, the focus system needs +//! multiple backends may be reporting that a pointer is hitting an entity, the hover system needs //! to determine which entities are actually being hovered by this pointer based on the pick depth, //! order of the backend, and the optional [`PickingBehavior`] component of the entity. In other words, //! if one entity is in front of another, usually only the topmost one will be hovered. @@ -154,7 +154,7 @@ extern crate alloc; pub mod backend; pub mod events; -pub mod focus; +pub mod hover; pub mod input; #[cfg(feature = "bevy_mesh_picking_backend")] pub mod mesh_picking; @@ -201,9 +201,9 @@ pub struct PickingBehavior { /// /// For example, if a pointer is over a UI element, as well as a 3d mesh, backends will report /// hits for both of these entities. Additionally, the hits will be sorted by the camera order, - /// so if the UI is drawing on top of the 3d mesh, the UI will be "above" the mesh. When focus + /// so if the UI is drawing on top of the 3d mesh, the UI will be "above" the mesh. When hovering /// is computed, the UI element will be checked first to see if it this field is set to block - /// lower entities. If it does (default), the focus system will stop there, and only the UI + /// lower entities. If it does (default), the hovering system will stop there, and only the UI /// element will be marked as hovered. However, if this field is set to `false`, both the UI /// element *and* the mesh will be marked as hovered. /// @@ -257,12 +257,12 @@ pub enum PickSet { ProcessInput, /// Reads inputs and produces [`backend::PointerHits`]s. In the [`PreUpdate`] schedule. Backend, - /// Reads [`backend::PointerHits`]s, and updates focus, selection, and highlighting states. In + /// Reads [`backend::PointerHits`]s, and updates the hovermap, selection, and highlighting states. In /// the [`PreUpdate`] schedule. - Focus, - /// Runs after all the focus systems are done, before event listeners are triggered. In the + Hover, + /// Runs after all the [`PickSet::Hover`] systems are done, before event listeners are triggered. In the /// [`PreUpdate`] schedule. - PostFocus, + PostHover, /// Runs after all other picking sets. In the [`PreUpdate`] schedule. Last, } @@ -298,7 +298,7 @@ pub struct PickingPlugin { /// Enables and disables input collection. pub is_input_enabled: bool, /// Enables and disables updating interaction states of entities. - pub is_focus_enabled: bool, + pub is_hover_enabled: bool, /// Enables or disables picking for window entities. pub is_window_picking_enabled: bool, } @@ -309,10 +309,10 @@ impl PickingPlugin { state.is_input_enabled && state.is_enabled } - /// Whether or not systems updating entities' [`PickingInteraction`](focus::PickingInteraction) + /// Whether or not systems updating entities' [`PickingInteraction`](hover::PickingInteraction) /// component should be running. - pub fn focus_should_run(state: Res) -> bool { - state.is_focus_enabled && state.is_enabled + pub fn hover_should_run(state: Res) -> bool { + state.is_hover_enabled && state.is_enabled } /// Whether or not window entities should receive pick events. @@ -326,7 +326,7 @@ impl Default for PickingPlugin { Self { is_enabled: true, is_input_enabled: true, - is_focus_enabled: true, + is_hover_enabled: true, is_window_picking_enabled: true, } } @@ -370,8 +370,8 @@ impl Plugin for PickingPlugin { ( PickSet::ProcessInput.run_if(Self::input_should_run), PickSet::Backend, - PickSet::Focus.run_if(Self::focus_should_run), - PickSet::PostFocus, + PickSet::Hover.run_if(Self::hover_should_run), + PickSet::PostHover, PickSet::Last, ) .chain(), @@ -393,10 +393,10 @@ pub struct InteractionPlugin; impl Plugin for InteractionPlugin { fn build(&self, app: &mut App) { use events::*; - use focus::{update_focus, update_interactions}; + use hover::{generate_hovermap, update_interactions}; - app.init_resource::() - .init_resource::() + app.init_resource::() + .init_resource::() .init_resource::() .add_event::>() .add_event::>() @@ -414,9 +414,9 @@ impl Plugin for InteractionPlugin { .add_event::>() .add_systems( PreUpdate, - (update_focus, update_interactions, pointer_events) + (generate_hovermap, update_interactions, pointer_events) .chain() - .in_set(PickSet::Focus), + .in_set(PickSet::Hover), ); } } diff --git a/examples/testbed/ui.rs b/examples/testbed/ui.rs index 677576cf12bf2..31805dd9a689f 100644 --- a/examples/testbed/ui.rs +++ b/examples/testbed/ui.rs @@ -7,7 +7,7 @@ use bevy::{ a11y::AccessibilityNode, color::palettes::{basic::LIME, css::DARK_GRAY}, input::mouse::{MouseScrollUnit, MouseWheel}, - picking::focus::HoverMap, + picking::hover::HoverMap, prelude::*, ui::widget::NodeImageMode, }; diff --git a/examples/ui/scroll.rs b/examples/ui/scroll.rs index c28abddd2a0c5..16a41328935f5 100644 --- a/examples/ui/scroll.rs +++ b/examples/ui/scroll.rs @@ -4,7 +4,7 @@ use accesskit::{Node as Accessible, Role}; use bevy::{ a11y::AccessibilityNode, input::mouse::{MouseScrollUnit, MouseWheel}, - picking::focus::HoverMap, + picking::hover::HoverMap, prelude::*, winit::WinitSettings, };