Skip to content

Commit

Permalink
Rename "focus" in bevy_picking to "hover" (#16872)
Browse files Browse the repository at this point in the history
# 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`
  • Loading branch information
alice-i-cecile authored Dec 24, 2024
1 parent 4a681c3 commit 48fe2a6
Show file tree
Hide file tree
Showing 5 changed files with 29 additions and 29 deletions.
8 changes: 4 additions & 4 deletions crates/bevy_picking/src/events.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
//!
Expand All @@ -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,
},
Expand Down Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ pub struct PreviousHoverMap(pub HashMap<PointerId, HashMap<Entity, HitData>>);

/// 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>,
Expand Down
44 changes: 22 additions & 22 deletions crates/bevy_picking/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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;
Expand Down Expand Up @@ -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.
///
Expand Down Expand Up @@ -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,
}
Expand Down Expand Up @@ -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,
}
Expand All @@ -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<Self>) -> bool {
state.is_focus_enabled && state.is_enabled
pub fn hover_should_run(state: Res<Self>) -> bool {
state.is_hover_enabled && state.is_enabled
}

/// Whether or not window entities should receive pick events.
Expand All @@ -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,
}
}
Expand Down Expand Up @@ -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(),
Expand All @@ -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::<focus::HoverMap>()
.init_resource::<focus::PreviousHoverMap>()
app.init_resource::<hover::HoverMap>()
.init_resource::<hover::PreviousHoverMap>()
.init_resource::<PointerState>()
.add_event::<Pointer<Cancel>>()
.add_event::<Pointer<Click>>()
Expand All @@ -414,9 +414,9 @@ impl Plugin for InteractionPlugin {
.add_event::<Pointer<Released>>()
.add_systems(
PreUpdate,
(update_focus, update_interactions, pointer_events)
(generate_hovermap, update_interactions, pointer_events)
.chain()
.in_set(PickSet::Focus),
.in_set(PickSet::Hover),
);
}
}
2 changes: 1 addition & 1 deletion examples/testbed/ui.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
};
Expand Down
2 changes: 1 addition & 1 deletion examples/ui/scroll.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
};
Expand Down

0 comments on commit 48fe2a6

Please sign in to comment.