Change core widgets to use callback enum instead of option (#19855)

# Objective

Because we want to be able to support more notification options in the
future (in addition to just using registered one-shot systems), the
`Option<SystemId>` notifications have been changed to a new enum,
`Callback`.

@alice-i-cecile

Author: viridia

crates/bevy_core_widgets/src/callback.rs

@@ -0,0 +1,113 @@
+use bevy_ecs::system::{Commands, SystemId, SystemInput};
+use bevy_ecs::world::{DeferredWorld, World};
+
+/// A callback defines how we want to be notified when a widget changes state. Unlike an event
+/// or observer, callbacks are intended for "point-to-point" communication that cuts across the
+/// hierarchy of entities. Callbacks can be created in advance of the entity they are attached
+/// to, and can be passed around as parameters.
+///
+/// Example:
+/// ```
+/// use bevy_app::App;
+/// use bevy_core_widgets::{Callback, Notify};
+/// use bevy_ecs::system::{Commands, IntoSystem};
+///
+/// let mut app = App::new();
+///
+/// // Register a one-shot system
+/// fn my_callback_system() {
+///     println!("Callback executed!");
+/// }
+///
+/// let system_id = app.world_mut().register_system(my_callback_system);
+///
+/// // Wrap system in a callback
+/// let callback = Callback::System(system_id);
+///
+/// // Later, when we want to execute the callback:
+/// app.world_mut().commands().notify(&callback);
+/// ```
+#[derive(Default, Debug)]
+pub enum Callback<I: SystemInput = ()> {
+    /// Invoke a one-shot system
+    System(SystemId<I>),
+    /// Ignore this notification
+    #[default]
+    Ignore,
+}
+
+/// Trait used to invoke a [`Callback`], unifying the API across callers.
+pub trait Notify {
+    /// Invoke the callback with no arguments.
+    fn notify(&mut self, callback: &Callback<()>);
+
+    /// Invoke the callback with one argument.
+    fn notify_with<I>(&mut self, callback: &Callback<I>, input: I::Inner<'static>)
+    where
+        I: SystemInput<Inner<'static>: Send> + 'static;
+}
+
+impl<'w, 's> Notify for Commands<'w, 's> {
+    fn notify(&mut self, callback: &Callback<()>) {
+        match callback {
+            Callback::System(system_id) => self.run_system(*system_id),
+            Callback::Ignore => (),
+        }
+    }
+
+    fn notify_with<I>(&mut self, callback: &Callback<I>, input: I::Inner<'static>)
+    where
+        I: SystemInput<Inner<'static>: Send> + 'static,
+    {
+        match callback {
+            Callback::System(system_id) => self.run_system_with(*system_id, input),
+            Callback::Ignore => (),
+        }
+    }
+}
+
+impl Notify for World {
+    fn notify(&mut self, callback: &Callback<()>) {
+        match callback {
+            Callback::System(system_id) => {
+                let _ = self.run_system(*system_id);
+            }
+            Callback::Ignore => (),
+        }
+    }
+
+    fn notify_with<I>(&mut self, callback: &Callback<I>, input: I::Inner<'static>)
+    where
+        I: SystemInput<Inner<'static>: Send> + 'static,
+    {
+        match callback {
+            Callback::System(system_id) => {
+                let _ = self.run_system_with(*system_id, input);
+            }
+            Callback::Ignore => (),
+        }
+    }
+}
+
+impl Notify for DeferredWorld<'_> {
+    fn notify(&mut self, callback: &Callback<()>) {
+        match callback {
+            Callback::System(system_id) => {
+                self.commands().run_system(*system_id);
+            }
+            Callback::Ignore => (),
+        }
+    }
+
+    fn notify_with<I>(&mut self, callback: &Callback<I>, input: I::Inner<'static>)
+    where
+        I: SystemInput<Inner<'static>: Send> + 'static,
+    {
+        match callback {
+            Callback::System(system_id) => {
+                self.commands().run_system_with(*system_id, input);
+            }
+            Callback::Ignore => (),
+        }
+    }
+}

crates/bevy_core_widgets/src/core_button.rs

@@ -7,24 +7,25 @@ use bevy_ecs::{
     entity::Entity,
     observer::On,
     query::With,
-    system::{Commands, Query, SystemId},
+    system::{Commands, Query},
 };
 use bevy_input::keyboard::{KeyCode, KeyboardInput};
 use bevy_input::ButtonState;
 use bevy_input_focus::FocusedInput;
 use bevy_picking::events::{Cancel, Click, DragEnd, Pointer, Press, Release};
 use bevy_ui::{InteractionDisabled, Pressed};
 
+use crate::{Callback, Notify};
+
 /// Headless button widget. This widget maintains a "pressed" state, which is used to
 /// indicate whether the button is currently being pressed by the user. It emits a `ButtonClicked`
 /// event when the button is un-pressed.
 #[derive(Component, Default, Debug)]
 #[require(AccessibilityNode(accesskit::Node::new(Role::Button)))]
 pub struct CoreButton {
-    /// Optional system to run when the button is clicked, or when the Enter or Space key
-    /// is pressed while the button is focused. If this field is `None`, the button will
-    /// emit a `ButtonClicked` event when clicked.
-    pub on_click: Option<SystemId>,
+    /// Callback to invoke when the button is clicked, or when the `Enter` or `Space` key
+    /// is pressed while the button is focused.
+    pub on_activate: Callback,
 }
 
 fn button_on_key_event(
@@ -39,10 +40,8 @@ fn button_on_key_event(
                 && event.state == ButtonState::Pressed
                 && (event.key_code == KeyCode::Enter || event.key_code == KeyCode::Space)
             {
-                if let Some(on_click) = bstate.on_click {
-                    trigger.propagate(false);
-                    commands.run_system(on_click);
-                }
+                trigger.propagate(false);
+                commands.notify(&bstate.on_activate);
             }
         }
     }
@@ -56,9 +55,7 @@ fn button_on_pointer_click(
     if let Ok((bstate, pressed, disabled)) = q_state.get_mut(trigger.target()) {
         trigger.propagate(false);
         if pressed && !disabled {
-            if let Some(on_click) = bstate.on_click {
-                commands.run_system(on_click);
-            }
+            commands.notify(&bstate.on_activate);
         }
     }
 }

crates/bevy_core_widgets/src/core_checkbox.rs

@@ -7,19 +7,21 @@ use bevy_ecs::system::{In, ResMut};
 use bevy_ecs::{
     component::Component,
     observer::On,
-    system::{Commands, Query, SystemId},
+    system::{Commands, Query},
 };
 use bevy_input::keyboard::{KeyCode, KeyboardInput};
 use bevy_input::ButtonState;
 use bevy_input_focus::{FocusedInput, InputFocus, InputFocusVisible};
 use bevy_picking::events::{Click, Pointer};
 use bevy_ui::{Checkable, Checked, InteractionDisabled};
 
+use crate::{Callback, Notify as _};
+
 /// Headless widget implementation for checkboxes. The [`Checked`] component represents the current
 /// state of the checkbox. The `on_change` field is an optional system id that will be run when the
 /// checkbox is clicked, or when the `Enter` or `Space` key is pressed while the checkbox is
-/// focused. If the `on_change` field is `None`, then instead of calling a callback, the checkbox
-/// will update its own [`Checked`] state directly.
+/// focused. If the `on_change` field is `Callback::Ignore`, then instead of calling a callback, the
+/// checkbox will update its own [`Checked`] state directly.
 ///
 /// # Toggle switches
 ///
@@ -29,8 +31,10 @@ use bevy_ui::{Checkable, Checked, InteractionDisabled};
 #[derive(Component, Debug, Default)]
 #[require(AccessibilityNode(accesskit::Node::new(Role::CheckBox)), Checkable)]
 pub struct CoreCheckbox {
-    /// One-shot system that is run when the checkbox state needs to be changed.
-    pub on_change: Option<SystemId<In<bool>>>,
+    /// One-shot system that is run when the checkbox state needs to be changed. If this value is
+    /// `Callback::Ignore`, then the checkbox will update it's own internal [`Checked`] state
+    /// without notification.
+    pub on_change: Callback<In<bool>>,
 }
 
 fn checkbox_on_key_input(
@@ -157,8 +161,8 @@ fn set_checkbox_state(
     checkbox: &CoreCheckbox,
     new_state: bool,
 ) {
-    if let Some(on_change) = checkbox.on_change {
-        commands.run_system_with(on_change, new_state);
+    if !matches!(checkbox.on_change, Callback::Ignore) {
+        commands.notify_with(&checkbox.on_change, new_state);
     } else if new_state {
         commands.entity(entity.into()).insert(Checked);
     } else {

crates/bevy_core_widgets/src/core_radio.rs

@@ -9,14 +9,16 @@ use bevy_ecs::{
     entity::Entity,
     observer::On,
     query::With,
-    system::{Commands, Query, SystemId},
+    system::{Commands, Query},
 };
 use bevy_input::keyboard::{KeyCode, KeyboardInput};
 use bevy_input::ButtonState;
 use bevy_input_focus::FocusedInput;
 use bevy_picking::events::{Click, Pointer};
 use bevy_ui::{Checkable, Checked, InteractionDisabled};
 
+use crate::{Callback, Notify};
+
 /// Headless widget implementation for a "radio button group". This component is used to group
 /// multiple [`CoreRadio`] components together, allowing them to behave as a single unit. It
 /// implements the tab navigation logic and keyboard shortcuts for radio buttons.
@@ -36,7 +38,7 @@ use bevy_ui::{Checkable, Checked, InteractionDisabled};
 #[require(AccessibilityNode(accesskit::Node::new(Role::RadioGroup)))]
 pub struct CoreRadioGroup {
     /// Callback which is called when the selected radio button changes.
-    pub on_change: Option<SystemId<In<Entity>>>,
+    pub on_change: Callback<In<Entity>>,
 }
 
 /// Headless widget implementation for radio buttons. These should be enclosed within a
@@ -131,9 +133,7 @@ fn radio_group_on_key_input(
             let (next_id, _) = radio_buttons[next_index];
 
             // Trigger the on_change event for the newly checked radio button
-            if let Some(on_change) = on_change {
-                commands.run_system_with(*on_change, next_id);
-            }
+            commands.notify_with(on_change, next_id);
         }
     }
 }
@@ -196,9 +196,7 @@ fn radio_group_on_button_click(
         }
 
         // Trigger the on_change event for the newly checked radio button
-        if let Some(on_change) = on_change {
-            commands.run_system_with(*on_change, radio_id);
-        }
+        commands.notify_with(on_change, radio_id);
     }
 }
 

crates/bevy_core_widgets/src/core_slider.rs

@@ -13,7 +13,7 @@ use bevy_ecs::{
     component::Component,
     observer::On,
     query::With,
-    system::{Commands, Query, SystemId},
+    system::{Commands, Query},
 };
 use bevy_input::keyboard::{KeyCode, KeyboardInput};
 use bevy_input::ButtonState;
@@ -22,6 +22,8 @@ use bevy_log::warn_once;
 use bevy_picking::events::{Drag, DragEnd, DragStart, Pointer, Press};
 use bevy_ui::{ComputedNode, ComputedNodeTarget, InteractionDisabled, UiGlobalTransform, UiScale};
 
+use crate::{Callback, Notify};
+
 /// Defines how the slider should behave when you click on the track (not the thumb).
 #[derive(Debug, Default, PartialEq, Clone, Copy)]
 pub enum TrackClick {
@@ -72,8 +74,9 @@ pub enum TrackClick {
 )]
 pub struct CoreSlider {
     /// Callback which is called when the slider is dragged or the value is changed via other user
-    /// interaction. If this value is `None`, then the slider will self-update.
-    pub on_change: Option<SystemId<In<f32>>>,
+    /// interaction. If this value is `Callback::Ignore`, then the slider will update it's own
+    /// internal [`SliderValue`] state without notification.
+    pub on_change: Callback<In<f32>>,
     /// Set the track-clicking behavior for this slider.
     pub track_click: TrackClick,
     // TODO: Think about whether we want a "vertical" option.
@@ -257,12 +260,12 @@ pub(crate) fn slider_on_pointer_down(
             TrackClick::Snap => click_val,
         });
 
-        if let Some(on_change) = slider.on_change {
-            commands.run_system_with(on_change, new_value);
-        } else {
+        if matches!(slider.on_change, Callback::Ignore) {
             commands
                 .entity(trigger.target())
                 .insert(SliderValue(new_value));
+        } else {
+            commands.notify_with(&slider.on_change, new_value);
         }
     }
 }
@@ -322,12 +325,12 @@ pub(crate) fn slider_on_drag(
                 range.start() + span * 0.5
             };
 
-            if let Some(on_change) = slider.on_change {
-                commands.run_system_with(on_change, new_value);
-            } else {
+            if matches!(slider.on_change, Callback::Ignore) {
                 commands
                     .entity(trigger.target())
                     .insert(SliderValue(new_value));
+            } else {
+                commands.notify_with(&slider.on_change, new_value);
             }
         }
     }
@@ -369,12 +372,12 @@ fn slider_on_key_input(
                 }
             };
             trigger.propagate(false);
-            if let Some(on_change) = slider.on_change {
-                commands.run_system_with(on_change, new_value);
-            } else {
+            if matches!(slider.on_change, Callback::Ignore) {
                 commands
                     .entity(trigger.target())
                     .insert(SliderValue(new_value));
+            } else {
+                commands.notify_with(&slider.on_change, new_value);
             }
         }
     }
@@ -461,12 +464,12 @@ fn slider_on_set_value(
                 range.clamp(value.0 + *delta * step.map(|s| s.0).unwrap_or_default())
             }
         };
-        if let Some(on_change) = slider.on_change {
-            commands.run_system_with(on_change, new_value);
-        } else {
+        if matches!(slider.on_change, Callback::Ignore) {
             commands
                 .entity(trigger.target())
                 .insert(SliderValue(new_value));
+        } else {
+            commands.notify_with(&slider.on_change, new_value);
         }
     }
 }

crates/bevy_core_widgets/src/lib.rs

@@ -14,6 +14,7 @@
 // styled/opinionated widgets that use them. Components which are directly exposed to users above
 // the widget level, like `SliderValue`, should not have the `Core` prefix.
 
+mod callback;
 mod core_button;
 mod core_checkbox;
 mod core_radio;
@@ -22,6 +23,7 @@ mod core_slider;
 
 use bevy_app::{App, Plugin};
 
+pub use callback::{Callback, Notify};
 pub use core_button::{CoreButton, CoreButtonPlugin};
 pub use core_checkbox::{CoreCheckbox, CoreCheckboxPlugin, SetChecked, ToggleChecked};
 pub use core_radio::{CoreRadio, CoreRadioGroup, CoreRadioGroupPlugin};