Skip to content

Adding interaction states for headless widgets. (ui only) #19349

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions crates/bevy_ui/src/interaction_states.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
/// This module contains components that are used to track the interaction state of UI widgets.
///
// Note to implementers: This uses a combination of both marker components and newtype components
// containing a bool. Markers are used for one-way binding, "write-only" components
// (like `InteractionDisabled`) that relay instructions from the user to the framework, whereas
// newtype components are used to request state updates from the framework, which mutates the
// content of those components on update.
use bevy_a11y::AccessibilityNode;
use bevy_ecs::{
component::{Component, HookContext},
world::DeferredWorld,
};

/// A marker component to indicate that a widget is disabled and should be "grayed out".
/// This is used to prevent user interaction with the widget. It should not, however, prevent
/// the widget from being updated or rendered, or from acquiring keyboard focus.
///
/// For apps which support a11y: if a widget (such as a slider) contains multiple entities,
/// the `InteractionDisabled` component should be added to the root entity of the widget - the
/// same entity that contains the `AccessibilityNode` component. This will ensure that
/// the a11y tree is updated correctly.
#[derive(Component, Debug, Clone, Copy)]
#[component(on_add = on_add_disabled, on_remove = on_remove_disabled)]
pub struct InteractionDisabled;

// Hook to set the a11y "disabled" state when the widget is disabled.
fn on_add_disabled(mut world: DeferredWorld, context: HookContext) {
let mut entity = world.entity_mut(context.entity);
if let Some(mut accessibility) = entity.get_mut::<AccessibilityNode>() {
accessibility.set_disabled();
}
}

// Hook to remove the a11y "disabled" state when the widget is enabled.
fn on_remove_disabled(mut world: DeferredWorld, context: HookContext) {
let mut entity = world.entity_mut(context.entity);
if let Some(mut accessibility) = entity.get_mut::<AccessibilityNode>() {
accessibility.clear_disabled();
}
}

/// Component that indicates whether a button is currently pressed.
#[derive(Component, Default, Debug)]
#[component(immutable)]
pub struct ButtonPressed(pub bool);

/// Component that indicates whether a checkbox or radio button is in a checked state.
#[derive(Component, Default, Debug)]
#[component(immutable, on_add = on_add_checked, on_replace = on_add_checked)]
pub struct Checked(pub bool);

// Hook to set the a11y "checked" state when the checkbox is added.
fn on_add_checked(mut world: DeferredWorld, context: HookContext) {
let mut entity = world.entity_mut(context.entity);
let checked = entity.get::<Checked>().unwrap().0;
let mut accessibility = entity.get_mut::<AccessibilityNode>().unwrap();
accessibility.set_toggled(match checked {
true => accesskit::Toggled::True,
false => accesskit::Toggled::False,
});
}
2 changes: 2 additions & 0 deletions crates/bevy_ui/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
//! Spawn UI elements with [`widget::Button`], [`ImageNode`], [`Text`](prelude::Text) and [`Node`]
//! This UI is laid out with the Flexbox and CSS Grid layout models (see <https://cssreference.io/flexbox/>)

pub mod interaction_states;
pub mod measurement;
pub mod ui_material;
pub mod update;
Expand Down Expand Up @@ -37,6 +38,7 @@ mod ui_node;
pub use focus::*;
pub use geometry::*;
pub use gradients::*;
pub use interaction_states::*;
pub use layout::*;
pub use measurement::*;
pub use render::*;
Expand Down
49 changes: 49 additions & 0 deletions release-content/release-notes/headless-widgets.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
title: Headless Widgets
authors: ["@viridia"]
pull_requests: [19238, 19349]
---

Bevy's `Button` and `Interaction` components have been around for a long time. Unfortunately
these components have a number of shortcomings, such as the fact that they don't use the new
`bevy_picking` framework, or the fact that they are really only useful for creating buttons
and not other kinds of widgets like sliders.

As an art form, games thrive on novelty: the typical game doesn't have boring, standardize controls
reminiscent of a productivity app, but instead will have beautiful, artistic widgets that are
in harmony with the game's overall visual theme. But writing new and unique widgets requires
skill and subtlety, particularly if we want first-class accessibility support. It's not a burden we
want to put on the average indie developer.

In the web development world, "headless" widget libraries, such as
[headlessui](https://headlessui.com/) and [reakit](https://reakit.io/) have become popular. These
provide standardized widgets that implement all of the correct interactions and behavioral logic,
including integration with screen readers, but which are unstyled. It's the responsibility of the
game developer to provide the visual style and animation for the widgets, which can fit the overall
style of their game.

With this release, Bevy introduces a collection of headless or "core" widgets. These are components
which can be added to any UI Node to get widget-like behavior. The core widget set includes buttons,
sliders, scrollbars, checkboxes, radio buttons, and more. This set will likely be expanded in
future releases.

## Widget Interaction States

Many of the core widgets will define supplementary ECS components that are used to store the widget's
state, similar to how the old `Interaction` component worked, but in a way that is more flexible.
These components include:

- `InteractionDisabled` - a marker component used to indicate that a component should be
"grayed out" and non-interactive. Note that these disabled widgets are still visible and can
have keyboard focus (otherwise the user would have no way to discover them).
- `Hovering` is a simple boolean component that allows detection of whether the widget is being
hovered using regular Bevy change detection.
- `Checked` is a boolean component that stores the checked state of a checkbox or radio button.
- `ButtonPressed` is used for a button-like widget, and will be true while the button is held down.

The combination of `Hovering` and `ButtonPressed` fulfills the same purpose as the old `Interaction`
component, except that now we can also represent "roll-off" behavior (the state where you click
on a button and then, while holding the mouse down, move the pointer out of the button's bounds).
It also provides additional flexibility in cases where a widget has multiple hoverable parts,
or cases where a widget is hoverable but doesn't have a pressed state (such as a tree-view expansion
toggle).