Interaction component refactor

Cargo.toml

@@ -2019,6 +2019,16 @@ description = "Illustrates how FontAtlases are populated (used to optimize text
 category = "UI (User Interface)"
 wasm = true
 
+[[example]]
+name = "press_policy"
+path = "examples/ui/press_policy.rs"
+
+[package.metadata.example.press_policy]
+name = "Press Policy"
+description = "Illustrates how the PressPolicy works with the Pressed component. Adds two buttons to the scene, one having a `Hold` press policy, and the other having a `Release` press policy."
+category = "UI (User Interface)"
+wasm = true
+
 [[example]]
 name = "overflow"
 path = "examples/ui/overflow.rs"

crates/bevy_ui/src/focus.rs

@@ -4,7 +4,7 @@ use bevy_ecs::{
     change_detection::DetectChangesMut,
     entity::Entity,
     prelude::{Component, With},
-    query::WorldQuery,
+    query::{Changed, Or, WorldQuery},
     reflect::ReflectComponent,
     system::{Local, Query, Res},
 };
@@ -18,41 +18,54 @@ use bevy_window::{PrimaryWindow, Window};
 use serde::{Deserialize, Serialize};
 use smallvec::SmallVec;
 
-/// Describes what type of input interaction has occurred for a UI node.
-///
-/// This is commonly queried with a `Changed<Interaction>` filter.
+/// Describes if a UI node has been pressed.
 ///
 /// Updated in [`ui_focus_system`].
 ///
-/// If a UI node has both [`Interaction`] and [`ViewVisibility`] components,
-/// [`Interaction`] will always be [`Interaction::None`]
+/// If a UI node has both [`Pressed`] and [`ViewVisibility`] components,
+/// the node will be considered not pressed
 /// when [`ViewVisibility::get()`] is false.
 /// This ensures that hidden UI nodes are not interactable,
 /// and do not end up stuck in an active state if hidden at the wrong time.
 ///
 /// Note that you can also control the visibility of a node using the [`Display`](crate::ui_node::Display) property,
 /// which fully collapses it during layout calculations.
-#[derive(Component, Copy, Clone, Eq, PartialEq, Debug, Reflect, Serialize, Deserialize)]
+#[derive(
+    Component, Copy, Clone, Eq, PartialEq, Debug, Default, Reflect, Serialize, Deserialize,
+)]
 #[reflect(Component, Serialize, Deserialize, PartialEq)]
-pub enum Interaction {
-    /// The node has been pressed.
-    ///
-    /// Note: This does not capture click/press-release action.
-    Pressed,
-    /// The node has been hovered over
-    Hovered,
-    /// Nothing has happened
-    None,
+pub struct Pressed {
+    /// Is the node currently pressed
+    pub pressed: bool,
+    /// Describes whether the component should remain in the pressed state after
+    /// the cursor stops hovering over the node.
+    pub press_policy: PressPolicy,
 }
 
-impl Interaction {
-    const DEFAULT: Self = Self::None;
+impl Pressed {
+    pub fn new(press_policy: PressPolicy) -> Self {
+        Self {
+            pressed: false,
+            press_policy,
+        }
+    }
 }
 
-impl Default for Interaction {
-    fn default() -> Self {
-        Self::DEFAULT
-    }
+/// Describes whether the [`Pressed`] component should remain in the pressed state after
+/// the cursor stops hovering over the node.
+///
+/// When the user clicks this node and the `PressPolicy` is set to `Hold`, the `Pressed` component will remain in the clicked state after the cursor leaves the node, until the user releases the interaction button. (the default behaviour)
+///
+/// If instead the `PressPolicy` is set to `Release`, the `Pressed` component will be considered not clicked
+/// as soon as the cursor leaves the node, even if the user still is pressing down the interaction button.
+#[derive(Copy, Clone, Default, Eq, PartialEq, Debug, Reflect, Serialize, Deserialize)]
+#[reflect(Serialize, Deserialize, PartialEq)]
+pub enum PressPolicy {
+    /// Keep the node clicked after it stopped being hovered
+    #[default]
+    Hold,
+    /// Release the node if the cursor stops hovering
+    Release,
 }
 
 /// A component storing the position of the mouse relative to the node, (0., 0.) being the top-left corner and (1., 1.) being the bottom-right
@@ -88,6 +101,61 @@ impl RelativeCursorPosition {
     }
 }
 
+/// A simplified interaction state calculated using the [`Pressed`] and [`RelativeCursorPosition`] components.
+///
+/// To see how to use this, see the [`InteractionStateHandler`] trait.
+#[derive(Copy, Clone, Eq, PartialEq, Debug, Reflect)]
+pub enum InteractionState {
+    None,
+    Hovered,
+    Pressed,
+}
+
+/// Simplified way to get the [`InteractionState`] of the node.
+///
+/// Example usage:
+/// ```rust
+/// use bevy_ecs::system::Query;
+/// use bevy_ui::InteractionStateHandler;
+/// use bevy_ui::InteractionState;
+/// use bevy_ui::Pressed;
+/// use bevy_ui::RelativeCursorPosition;
+///
+/// fn button_system(button_query: Query<(&Pressed, &RelativeCursorPosition)>) {
+///     let button = button_query.single();
+///
+///     match button.interaction_state() {
+///         InteractionState::None => (),
+///         InteractionState::Hovered => {
+///             println!("The button is being hovered over");
+///         },
+///         InteractionState::Pressed => {
+///             println!("The button is being pressed");
+///         },
+///    }
+/// }
+/// ```
+pub trait InteractionStateHandler {
+    fn interaction_state(&self) -> InteractionState;
+}
+
+impl InteractionStateHandler for (&Pressed, &RelativeCursorPosition) {
+    /// Get the [`InteractionState`] of the node
+    fn interaction_state(&self) -> InteractionState {
+        if self.0.pressed {
+            return InteractionState::Pressed;
+        }
+
+        if self.1.mouse_over() {
+            return InteractionState::Hovered;
+        }
+
+        InteractionState::None
+    }
+}
+
+pub type InteractionStateChangedFilter = Or<(Changed<Pressed>, Changed<RelativeCursorPosition>)>;
+
 /// Describes whether the node should block interactions with lower nodes
 #[derive(Component, Copy, Clone, Eq, PartialEq, Debug, Reflect, Serialize, Deserialize)]
 #[reflect(Component, Serialize, Deserialize, PartialEq)]
@@ -121,7 +189,7 @@ pub struct NodeQuery {
     entity: Entity,
     node: &'static Node,
     global_transform: &'static GlobalTransform,
-    interaction: Option<&'static mut Interaction>,
+    pressed_state: Option<&'static mut Pressed>,
     relative_cursor_position: Option<&'static mut RelativeCursorPosition>,
     focus_policy: Option<&'static FocusPolicy>,
     calculated_clip: Option<&'static CalculatedClip>,
@@ -147,18 +215,18 @@ pub fn ui_focus_system(
 
     // reset entities that were both clicked and released in the last frame
     for entity in state.entities_to_reset.drain(..) {
-        if let Ok(mut interaction) = node_query.get_component_mut::<Interaction>(entity) {
-            *interaction = Interaction::None;
+        if let Ok(mut pressed_state) = node_query.get_component_mut::<Pressed>(entity) {
+            pressed_state.pressed = false;
         }
     }
 
     let mouse_released =
         mouse_button_input.just_released(MouseButton::Left) || touches_input.any_just_released();
     if mouse_released {
         for node in node_query.iter_mut() {
-            if let Some(mut interaction) = node.interaction {
-                if *interaction == Interaction::Pressed {
-                    *interaction = Interaction::None;
+            if let Some(mut pressed_state) = node.pressed_state {
+                if pressed_state.pressed {
+                    pressed_state.pressed = false;
                 }
             }
         }
@@ -207,9 +275,12 @@ pub fn ui_focus_system(
                 if let Some(view_visibility) = node.view_visibility {
                     if !view_visibility.get() {
                         // Reset their interaction to None to avoid strange stuck state
-                        if let Some(mut interaction) = node.interaction {
+                        if let Some(mut pressed_state) = node.pressed_state {
                             // We cannot simply set the interaction to None, as that will trigger change detection repeatedly
-                            interaction.set_if_neq(Interaction::None);
+                            pressed_state.set_if_neq(Pressed {
+                                pressed: false,
+                                ..*pressed_state
+                            });
                         }
 
                         return None;
@@ -247,9 +318,17 @@ pub fn ui_focus_system(
                 if contains_cursor {
                     Some(*entity)
                 } else {
-                    if let Some(mut interaction) = node.interaction {
-                        if *interaction == Interaction::Hovered || (cursor_position.is_none()) {
-                            interaction.set_if_neq(Interaction::None);
+                    if let Some(mut pressed_state) = node.pressed_state {
+                        // If the InteractionPolicy is Release, we should set the interaction to None
+                        // The entity might just as well not have the InteractionPolicy component
+                        // in which case we should use the default behaviour
+                        let interaction_policy = pressed_state.press_policy;
+
+                        if cursor_position.is_none() || interaction_policy == PressPolicy::Release {
+                            pressed_state.set_if_neq(Pressed {
+                                pressed: false,
+                                ..*pressed_state
+                            });
                         }
                     }
                     None
@@ -265,19 +344,14 @@ pub fn ui_focus_system(
     // the iteration will stop on it because it "captures" the interaction.
     let mut iter = node_query.iter_many_mut(hovered_nodes.by_ref());
     while let Some(node) = iter.fetch_next() {
-        if let Some(mut interaction) = node.interaction {
-            if mouse_clicked {
-                // only consider nodes with Interaction "pressed"
-                if *interaction != Interaction::Pressed {
-                    *interaction = Interaction::Pressed;
-                    // if the mouse was simultaneously released, reset this Interaction in the next
-                    // frame
-                    if mouse_released {
-                        state.entities_to_reset.push(node.entity);
-                    }
+        if let Some(mut pressed_state) = node.pressed_state {
+            if mouse_clicked && !pressed_state.pressed {
+                pressed_state.pressed = true;
+                // if the mouse was simultaneously released, reset this Interaction in the next
+                // frame
+                if mouse_released {
+                    state.entities_to_reset.push(node.entity);
                 }
-            } else if *interaction == Interaction::None {
-                *interaction = Interaction::Hovered;
             }
         }
 
@@ -292,10 +366,13 @@ pub fn ui_focus_system(
     // `moused_over_nodes` after the previous loop is exited.
     let mut iter = node_query.iter_many_mut(hovered_nodes);
     while let Some(node) = iter.fetch_next() {
-        if let Some(mut interaction) = node.interaction {
-            // don't reset pressed nodes because they're handled separately
-            if *interaction != Interaction::Pressed {
-                interaction.set_if_neq(Interaction::None);
+        if let Some(mut pressed_state) = node.pressed_state {
+            // don't reset clicked nodes because they're handled separately
+            if !pressed_state.pressed {
+                pressed_state.set_if_neq(Pressed {
+                    pressed: false,
+                    ..*pressed_state
+                });
             }
         }
     }

crates/bevy_ui/src/lib.rs

@@ -35,7 +35,7 @@ pub mod prelude {
     #[doc(hidden)]
     pub use crate::{
         camera_config::*, geometry::*, node_bundles::*, ui_node::*, widget::Button, widget::Label,
-        Interaction, UiScale,
+        Pressed, UiScale,
     };
 }
 
@@ -98,7 +98,10 @@ impl Plugin for UiPlugin {
             .register_type::<GridAutoFlow>()
             .register_type::<GridPlacement>()
             .register_type::<GridTrack>()
-            .register_type::<Interaction>()
+            .register_type::<RepeatedGridTrack>()
+            .register_type::<FocusPolicy>()
+            .register_type::<Pressed>()
+            .register_type::<PressPolicy>()
             .register_type::<JustifyContent>()
             .register_type::<JustifyItems>()
             .register_type::<JustifySelf>()

crates/bevy_ui/src/node_bundles.rs

@@ -4,8 +4,8 @@
 use crate::widget::TextFlags;
 use crate::{
     widget::{Button, UiImageSize},
-    BackgroundColor, BorderColor, ContentSize, FocusPolicy, Interaction, Node, Style, UiImage,
-    UiTextureAtlasImage, ZIndex,
+    BackgroundColor, BorderColor, ContentSize, FocusPolicy, Node, Pressed, RelativeCursorPosition,
+    Style, UiImage, UiTextureAtlasImage, ZIndex,
 };
 use bevy_asset::Handle;
 use bevy_ecs::bundle::Bundle;
@@ -278,8 +278,12 @@ pub struct ButtonBundle {
     /// Styles which control the layout (size and position) of the node and it's children
     /// In some cases these styles also affect how the node drawn/painted.
     pub style: Style,
-    /// Describes whether and how the button has been interacted with by the input
-    pub interaction: Interaction,
+    /// Describes whether the button is pressed
+    pub pressed: Pressed,
+    /// The position of the cursor relative to the node
+    ///
+    /// Used for checking if the cursor is hovering over the node
+    pub relative_cursor_position: RelativeCursorPosition,
     /// Whether this node should block interaction with lower nodes
     pub focus_policy: FocusPolicy,
     /// The background color, which serves as a "fill" for this node
@@ -317,7 +321,8 @@ impl Default for ButtonBundle {
             button: Default::default(),
             style: Default::default(),
             border_color: BorderColor(Color::NONE),
-            interaction: Default::default(),
+            pressed: Default::default(),
+            relative_cursor_position: Default::default(),
             background_color: Default::default(),
             image: Default::default(),
             transform: Default::default(),

examples/README.md

@@ -348,6 +348,7 @@ Example | Description
 [Font Atlas Debug](../examples/ui/font_atlas_debug.rs) | Illustrates how FontAtlases are populated (used to optimize text rendering internally)
 [Overflow](../examples/ui/overflow.rs) | Simple example demonstrating overflow behavior
 [Overflow and Clipping Debug](../examples/ui/overflow_debug.rs) | An example to debug overflow and clipping behavior
+[Press Policy](../examples/ui/press_policy.rs) | Illustrates how the PressPolicy works with the Pressed component. Adds two buttons to the scene, one having a `Hold` press policy, and the other having a `Release` press policy.
 [Relative Cursor Position](../examples/ui/relative_cursor_position.rs) | Showcases the RelativeCursorPosition component
 [Size Constraints](../examples/ui/size_constraints.rs) | Demonstrates how the to use the size constraints to control the size of a UI node.
 [Text](../examples/ui/text.rs) | Illustrates creating and updating text

examples/ecs/state.rs

@@ -5,7 +5,13 @@
 //!
 //! In this case, we're transitioning from a `Menu` state to an `InGame` state.
 
-use bevy::prelude::*;
+use bevy::{
+    prelude::*,
+    ui::{
+        InteractionState, InteractionStateChangedFilter, InteractionStateHandler,
+        RelativeCursorPosition,
+    },
+};
 
 fn main() {
     App::new()
@@ -93,20 +99,20 @@ fn setup_menu(mut commands: Commands) {
 fn menu(
     mut next_state: ResMut<NextState<AppState>>,
     mut interaction_query: Query<
-        (&Interaction, &mut BackgroundColor),
-        (Changed<Interaction>, With<Button>),
+        (&Pressed, &RelativeCursorPosition, &mut BackgroundColor),
+        (InteractionStateChangedFilter, With<Button>),
     >,
 ) {
-    for (interaction, mut color) in &mut interaction_query {
-        match *interaction {
-            Interaction::Pressed => {
+    for (interaction, relative_cursor_position, mut color) in &mut interaction_query {
+        match (interaction, relative_cursor_position).interaction_state() {
+            InteractionState::Pressed => {
                 *color = PRESSED_BUTTON.into();
                 next_state.set(AppState::InGame);
             }
-            Interaction::Hovered => {
+            InteractionState::Hovered => {
                 *color = HOVERED_BUTTON.into();
             }
-            Interaction::None => {
+            InteractionState::None => {
                 *color = NORMAL_BUTTON.into();
             }
         }