Text Rework cleanup (#15887)

# Objective

Cleanup naming and docs, add missing migration guide after #15591 

All text root nodes now use `Text` (UI) / `Text2d`.
All text readers/writers use `Text<Type>Reader`/`Text<Type>Writer`
convention.

---

## Migration Guide

Doubles as #15591 migration guide.

Text bundles (`TextBundle` and `Text2dBundle`) were removed in favor of
`Text` and `Text2d`.
Shared configuration fields were replaced with `TextLayout`, `TextFont`
and `TextColor` components.
Just `TextBundle`'s additional field turned into `TextNodeFlags`
component,
while `Text2dBundle`'s additional fields turned into `TextBounds` and
`Anchor` components.

Text sections were removed in favor of hierarchy-based approach.
For root text entities with `Text` or `Text2d` components, child
entities with `TextSpan` will act as additional text sections.
To still access text spans by index, use the new `TextUiReader`,
`Text2dReader` and `TextUiWriter`, `Text2dWriter` system parameters.
This commit is contained in:
MiniaczQ 2024-10-15 04:32:34 +02:00 committed by GitHub
parent 73f7fd0c12
commit f602edad09
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
30 changed files with 88 additions and 55 deletions

View file

@ -17,7 +17,7 @@ use bevy_render::view::Visibility;
use bevy_text::{Font, TextColor, TextFont, TextSpan};
use bevy_ui::{
node_bundles::NodeBundle,
widget::{Text, UiTextWriter},
widget::{Text, TextUiWriter},
GlobalZIndex, PositionType, Style,
};
use bevy_utils::default;
@ -114,7 +114,7 @@ fn setup(mut commands: Commands, overlay_config: Res<FpsOverlayConfig>) {
fn update_text(
diagnostic: Res<DiagnosticsStore>,
query: Query<Entity, With<FpsText>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
for entity in &query {
if let Some(fps) = diagnostic.get(&FrameTimeDiagnosticsPlugin::FPS) {
@ -128,7 +128,7 @@ fn update_text(
fn customize_text(
overlay_config: Res<FpsOverlayConfig>,
query: Query<Entity, With<FpsText>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
for entity in &query {
writer.for_each_font(entity, |mut font| {

View file

@ -63,10 +63,13 @@ pub use text_access::*;
///
/// This includes the most common types in this crate, re-exported for your convenience.
pub mod prelude {
#[doc(hidden)]
#[allow(deprecated)]
pub use crate::Text2dBundle;
#[doc(hidden)]
pub use crate::{
Font, JustifyText, LineBreak, Text2d, TextColor, TextError, TextFont, TextLayout,
TextReader2d, TextSpan, TextWriter2d,
Font, JustifyText, LineBreak, Text2d, Text2dReader, Text2dWriter, TextColor, TextError,
TextFont, TextLayout, TextSpan,
};
}

View file

@ -32,6 +32,18 @@ use bevy_transform::prelude::GlobalTransform;
use bevy_utils::HashSet;
use bevy_window::{PrimaryWindow, Window, WindowScaleFactorChanged};
/// [`Text2dBundle`] was removed in favor of required components.
/// The core component is now [`Text2d`] which can contain a single text segment.
/// Indexed access to segments can be done with the new [`Text2dReader`] and [`Text2dWriter`] system params.
/// Additional segments can be added through children with [`TextSpan`](crate::text::TextSpan).
/// Text configuration can be done with [`TextLayout`], [`TextFont`] and [`TextColor`],
/// while sprite-related configuration uses [`TextBounds`] and [`Anchor`] components.
#[deprecated(
since = "0.15.0",
note = "Text2dBundle has been migrated to required components. Follow the documentation for more information."
)]
pub struct Text2dBundle {}
/// The top-level 2D text component.
///
/// Adding `Text2d` to an entity will pull in required components for setting up 2d text.
@ -120,10 +132,10 @@ impl From<String> for Text2d {
}
/// 2d alias for [`TextReader`].
pub type TextReader2d<'w, 's> = TextReader<'w, 's, Text2d>;
pub type Text2dReader<'w, 's> = TextReader<'w, 's, Text2d>;
/// 2d alias for [`TextWriter`].
pub type TextWriter2d<'w, 's> = TextWriter<'w, 's, Text2d>;
pub type Text2dWriter<'w, 's> = TextWriter<'w, 's, Text2d>;
/// This system extracts the sprites from the 2D text components and adds them to the
/// "render world".
@ -239,7 +251,7 @@ pub fn update_text2d_layout(
&mut TextLayoutInfo,
&mut ComputedTextBlock,
)>,
mut text_reader: TextReader2d,
mut text_reader: Text2dReader,
mut font_system: ResMut<CosmicFontSystem>,
mut swash_cache: ResMut<SwashCache>,
) {

View file

@ -45,7 +45,7 @@ impl TextIterScratch {
/// System parameter for reading text spans in a text block.
///
/// `R` is the root text component, and `S` is the text span component on children.
/// `R` is the root text component.
#[derive(SystemParam)]
pub struct TextReader<'w, 's, R: TextRoot> {
// This is a local to avoid system ambiguities when TextReaders run in parallel.

View file

@ -1,6 +1,6 @@
use crate::{
prelude::{Button, Label},
widget::UiTextReader,
widget::TextUiReader,
Node, UiChildren, UiImage,
};
use bevy_a11y::{
@ -19,7 +19,7 @@ use bevy_render::{camera::CameraUpdateSystem, prelude::Camera};
use bevy_transform::prelude::GlobalTransform;
fn calc_name(
text_reader: &mut UiTextReader,
text_reader: &mut TextUiReader,
children: impl Iterator<Item = Entity>,
) -> Option<Box<str>> {
let mut name = None;
@ -62,7 +62,7 @@ fn button_changed(
mut commands: Commands,
mut query: Query<(Entity, Option<&mut AccessibilityNode>), Changed<Button>>,
ui_children: UiChildren,
mut text_reader: UiTextReader,
mut text_reader: TextUiReader,
) {
for (entity, accessible) in &mut query {
let name = calc_name(&mut text_reader, ui_children.iter_ui_children(entity));
@ -89,7 +89,7 @@ fn image_changed(
mut commands: Commands,
mut query: Query<(Entity, Option<&mut AccessibilityNode>), (Changed<UiImage>, Without<Button>)>,
ui_children: UiChildren,
mut text_reader: UiTextReader,
mut text_reader: TextUiReader,
) {
for (entity, accessible) in &mut query {
let name = calc_name(&mut text_reader, ui_children.iter_ui_children(entity));
@ -115,7 +115,7 @@ fn image_changed(
fn label_changed(
mut commands: Commands,
mut query: Query<(Entity, Option<&mut AccessibilityNode>), Changed<Label>>,
mut text_reader: UiTextReader,
mut text_reader: TextUiReader,
) {
for (entity, accessible) in &mut query {
let values = text_reader

View file

@ -46,6 +46,12 @@ use widget::UiImageSize;
///
/// This includes the most common types in this crate, re-exported for your convenience.
pub mod prelude {
#[allow(deprecated)]
#[doc(hidden)]
pub use crate::widget::TextBundle;
#[cfg(feature = "bevy_text")]
#[doc(hidden)]
pub use crate::widget::{Text, TextUiReader, TextUiWriter};
#[doc(hidden)]
pub use {
crate::{
@ -53,7 +59,7 @@ pub mod prelude {
node_bundles::*,
ui_material::*,
ui_node::*,
widget::{Button, Label, Text, UiTextReader, UiTextWriter},
widget::{Button, Label},
Interaction, UiMaterialHandle, UiMaterialPlugin, UiScale,
},
// `bevy_sprite` re-exports for texture slicing

View file

@ -48,6 +48,18 @@ impl Default for TextNodeFlags {
}
}
/// [`TextBundle`] was removed in favor of required components.
/// The core component is now [`Text`] which can contain a single text segment.
/// Indexed access to segments can be done with the new [`TextUiReader`] and [`TextUiWriter`] system params.
/// Additional segments can be added through children with [`TextSpan`](bevy_text::TextSpan).
/// Text configuration can be done with [`TextLayout`], [`TextFont`] and [`TextColor`],
/// while node-related configuration uses [`TextNodeFlags`] component.
#[deprecated(
since = "0.15.0",
note = "TextBundle has been migrated to required components. Follow the documentation for more information."
)]
pub struct TextBundle {}
/// The top-level UI text component.
///
/// Adding [`Text`] to an entity will pull in required components for setting up a UI text node.
@ -137,10 +149,10 @@ impl From<String> for Text {
}
/// UI alias for [`TextReader`].
pub type UiTextReader<'w, 's> = TextReader<'w, 's, Text>;
pub type TextUiReader<'w, 's> = TextReader<'w, 's, Text>;
/// UI alias for [`TextWriter`].
pub type UiTextWriter<'w, 's> = TextWriter<'w, 's, Text>;
pub type TextUiWriter<'w, 's> = TextWriter<'w, 's, Text>;
/// Text measurement for UI layout. See [`NodeMeasure`].
pub struct TextMeasure {
@ -273,7 +285,7 @@ pub fn measure_text_system(
),
With<Node>,
>,
mut text_reader: UiTextReader,
mut text_reader: TextUiReader,
mut text_pipeline: ResMut<TextPipeline>,
mut font_system: ResMut<CosmicFontSystem>,
) {
@ -336,7 +348,7 @@ fn queue_text(
mut text_flags: Mut<TextNodeFlags>,
text_layout_info: Mut<TextLayoutInfo>,
computed: &mut ComputedTextBlock,
text_reader: &mut UiTextReader,
text_reader: &mut TextUiReader,
font_system: &mut CosmicFontSystem,
swash_cache: &mut SwashCache,
) {
@ -416,7 +428,7 @@ pub fn text_system(
&mut ComputedTextBlock,
Option<&TargetCamera>,
)>,
mut text_reader: UiTextReader,
mut text_reader: TextUiReader,
mut font_system: ResMut<CosmicFontSystem>,
mut swash_cache: ResMut<SwashCache>,
) {

View file

@ -561,7 +561,7 @@ fn update_ui_state(
)>,
button_text: Query<(Entity, &ColorGradingOptionWidget), (With<Text>, Without<HelpText>)>,
help_text: Single<Entity, With<HelpText>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
cameras: Single<Ref<ColorGrading>>,
currently_selected_option: Res<SelectedColorGradingOption>,
) {

View file

@ -255,7 +255,7 @@ fn update_exposure(
mut parameters: ResMut<Parameters>,
mut exposure: Single<&mut Exposure>,
text: Single<Entity, With<Text>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
// TODO: Clamp values to a reasonable range
let entity = *text;

View file

@ -254,7 +254,7 @@ fn keyboard_inputs(
mut motion_blur: Single<&mut MotionBlur>,
presses: Res<ButtonInput<KeyCode>>,
text: Single<Entity, With<Text>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
mut camera: ResMut<CameraMode>,
) {
if presses.just_pressed(KeyCode::Digit1) {

View file

@ -67,7 +67,7 @@ fn toggle_oit(
text: Single<Entity, With<Text>>,
keyboard_input: Res<ButtonInput<KeyCode>>,
q: Single<(Entity, Has<OrderIndependentTransparencySettings>), With<Camera3d>>,
mut text_writer: UiTextWriter,
mut text_writer: TextUiWriter,
) {
if keyboard_input.just_pressed(KeyCode::KeyT) {
let (e, has_oit) = *q;

View file

@ -80,7 +80,7 @@ fn update_parallax_depth_scale(
mut materials: ResMut<Assets<StandardMaterial>>,
mut target_depth: Local<TargetDepth>,
mut depth_update: Local<bool>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
text: Single<Entity, With<Text>>,
) {
if input.just_pressed(KeyCode::Digit1) {
@ -110,7 +110,7 @@ fn switch_method(
input: Res<ButtonInput<KeyCode>>,
mut materials: ResMut<Assets<StandardMaterial>>,
text: Single<Entity, With<Text>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
mut current: Local<CurrentMethod>,
) {
if input.just_pressed(KeyCode::Space) {
@ -131,7 +131,7 @@ fn update_parallax_layers(
mut materials: ResMut<Assets<StandardMaterial>>,
mut target_layers: Local<TargetLayers>,
text: Single<Entity, With<Text>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
if input.just_pressed(KeyCode::Digit3) {
target_layers.0 -= 1.0;

View file

@ -258,7 +258,7 @@ fn update_radio_buttons(
Or<(With<RadioButton>, With<RadioButtonText>)>,
>,
app_status: Res<AppStatus>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
for (entity, image, has_text, sender) in widgets.iter_mut() {
let selected = match **sender {

View file

@ -153,7 +153,7 @@ fn toggle_light(
mut point_lights: Query<&mut PointLight>,
mut directional_lights: Query<&mut DirectionalLight>,
example_text: Single<Entity, With<Text>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
if input.just_pressed(KeyCode::KeyL) {
for mut light in &mut point_lights {
@ -179,7 +179,7 @@ fn adjust_light_position(
input: Res<ButtonInput<KeyCode>>,
mut lights: Query<&mut Transform, With<Lights>>,
example_text: Single<Entity, With<Text>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
let mut offset = Vec3::ZERO;
if input.just_pressed(KeyCode::ArrowLeft) {
@ -216,7 +216,7 @@ fn cycle_filter_methods(
input: Res<ButtonInput<KeyCode>>,
mut filter_methods: Query<&mut ShadowFilteringMethod>,
example_text: Single<Entity, With<Text>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
if input.just_pressed(KeyCode::KeyF) {
for mut filter_method in &mut filter_methods {
@ -244,7 +244,7 @@ fn adjust_point_light_biases(
input: Res<ButtonInput<KeyCode>>,
mut query: Query<&mut PointLight>,
example_text: Single<Entity, With<Text>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
let depth_bias_step_size = 0.01;
let normal_bias_step_size = 0.1;
@ -279,7 +279,7 @@ fn adjust_directional_light_biases(
input: Res<ButtonInput<KeyCode>>,
mut query: Query<&mut DirectionalLight>,
example_text: Single<Entity, With<Text>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
let depth_bias_step_size = 0.01;
let normal_bias_step_size = 0.1;

View file

@ -474,7 +474,7 @@ fn handle_button_toggles(
fn update_ui(
mut animation_controls: Query<(&AnimationControl, &mut BackgroundColor, &Children)>,
texts: Query<Entity, With<Text>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
app_state: Res<AppState>,
) {
for (animation_control, mut background_color, kids) in animation_controls.iter_mut() {

View file

@ -79,12 +79,12 @@ fn evaluate_callbacks(query: Query<(Entity, &Callback), With<Triggered>>, mut co
}
}
fn system_a(entity_a: Single<Entity, With<Text>>, mut writer: UiTextWriter) {
fn system_a(entity_a: Single<Entity, With<Text>>, mut writer: TextUiWriter) {
*writer.text(*entity_a, 3) = String::from("A");
info!("A: One shot system registered with Commands was triggered");
}
fn system_b(entity_b: Single<Entity, With<Text>>, mut writer: UiTextWriter) {
fn system_b(entity_b: Single<Entity, With<Text>>, mut writer: TextUiWriter) {
*writer.text(*entity_b, 3) = String::from("B");
info!("B: One shot system registered with World was triggered");
}

View file

@ -336,7 +336,7 @@ fn apply_velocity(mut query: Query<(&mut Transform, &Velocity)>, time: Res<Time>
fn update_scoreboard(
score: Res<Score>,
score_root: Single<Entity, (With<ScoreboardUi>, With<Text>)>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
*writer.text(*score_root, 1) = score.to_string();
}

View file

@ -161,7 +161,7 @@ fn selection(
mut contributor_selection: ResMut<ContributorSelection>,
contributor_root: Single<Entity, (With<ContributorDisplay>, With<Text>)>,
mut query: Query<(&Contributor, &mut Sprite, &mut Transform)>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
time: Res<Time>,
) {
if !timer.0.tick(time.delta()).just_finished() {
@ -204,7 +204,7 @@ fn select(
contributor: &Contributor,
transform: &mut Transform,
entity: Entity,
writer: &mut UiTextWriter,
writer: &mut TextUiWriter,
) {
sprite.color = SELECTED.with_hue(contributor.hue).into();

View file

@ -240,7 +240,7 @@ fn update_ui(
state: Res<State>,
stepping: Res<Stepping>,
ui: Single<(Entity, &Visibility), With<SteppingUi>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
// ensure the UI is only visible when stepping is enabled
let (ui, vis) = *ui;

View file

@ -145,7 +145,7 @@ fn update_config(
keyboard: Res<ButtonInput<KeyCode>>,
time: Res<Time>,
color_text_query: Single<Entity, With<GizmoColorText>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
if keyboard.just_pressed(KeyCode::KeyD) {
for (_, config, _) in config_store.iter_mut() {

View file

@ -168,7 +168,7 @@ pub fn update_ui_radio_button(background_color: &mut BackgroundColor, selected:
/// Updates the color of the label of a radio button to reflect its selected
/// status.
pub fn update_ui_radio_button_text(entity: Entity, writer: &mut UiTextWriter, selected: bool) {
pub fn update_ui_radio_button_text(entity: Entity, writer: &mut TextUiWriter, selected: bool) {
let text_color = if selected { Color::BLACK } else { Color::WHITE };
writer.for_each_color(entity, |mut color| {

View file

@ -76,7 +76,7 @@ fn toggle_ime(
input: Res<ButtonInput<MouseButton>>,
mut window: Single<&mut Window>,
status_text: Single<Entity, (With<Node>, With<Text>)>,
mut ui_writer: UiTextWriter,
mut ui_writer: TextUiWriter,
) {
if input.just_pressed(MouseButton::Left) {
window.ime_position = window.cursor_position().unwrap();
@ -108,7 +108,7 @@ fn listen_ime_events(
mut events: EventReader<Ime>,
status_text: Single<Entity, (With<Node>, With<Text>)>,
mut edit_text: Single<&mut Text2d, (Without<Node>, Without<Bubble>)>,
mut ui_writer: UiTextWriter,
mut ui_writer: TextUiWriter,
) {
for event in events.read() {
match event {

View file

@ -408,7 +408,7 @@ fn setup_text(mut commands: Commands, cameras: Query<(Entity, &Camera)>) {
fn update_text(
primitive_state: Res<State<PrimitiveSelected>>,
header: Query<Entity, With<HeaderText>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
let new_text = format!("{text}", text = primitive_state.get());
header.iter().for_each(|header_text| {

View file

@ -215,7 +215,7 @@ fn toggle_prepass_view(
material_handle: Single<&MeshMaterial3d<PrepassOutputMaterial>>,
mut materials: ResMut<Assets<PrepassOutputMaterial>>,
text: Single<Entity, With<Text>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
if keycode.just_pressed(KeyCode::Space) {
*prepass_view = (*prepass_view + 1) % 4;

View file

@ -547,7 +547,7 @@ fn counter_system(
diagnostics: Res<DiagnosticsStore>,
counter: Res<BevyCounter>,
query: Single<Entity, With<StatsText>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
let text = *query;

View file

@ -421,7 +421,7 @@ fn update_axes(
mut axis_events: EventReader<GamepadAxisChangedEvent>,
mut query: Query<(&mut Transform, &MoveWithAxes)>,
text_query: Query<(Entity, &TextWithAxes)>,
mut writer: TextWriter2d,
mut writer: Text2dWriter,
) {
for axis_event in axis_events.read() {
let axis_type = axis_event.axis;
@ -449,7 +449,7 @@ fn update_connected(
mut connected: EventReader<GamepadConnectionEvent>,
gamepads: Query<(Entity, &Gamepad)>,
text: Single<Entity, With<ConnectedGamepadsText>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
if connected.is_empty() {
return;

View file

@ -180,7 +180,7 @@ fn update_text(
controls: Option<ResMut<WeightsControl>>,
text: Single<Entity, With<Text>>,
morphs: Query<&MorphWeights>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
let Some(mut controls) = controls else {
return;

View file

@ -1,6 +1,6 @@
//! Tests how different transforms behave when clipped with `Overflow::Hidden`
use bevy::{input::common_conditions::input_just_pressed, prelude::*, ui::widget::UiTextWriter};
use bevy::{input::common_conditions::input_just_pressed, prelude::*, ui::widget::TextUiWriter};
use std::f32::consts::{FRAC_PI_2, PI, TAU};
const CONTAINER_SIZE: f32 = 150.0;
@ -259,7 +259,7 @@ fn update_transform<T: UpdateTransform + Component>(
fn toggle_overflow(
mut containers: Query<&mut Style, With<Container>>,
instructions: Single<Entity, With<Instructions>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
for mut style in &mut containers {
style.overflow = match style.overflow {

View file

@ -6,7 +6,7 @@ use bevy::{
color::palettes::css::*,
diagnostic::{DiagnosticsStore, FrameTimeDiagnosticsPlugin},
prelude::*,
ui::widget::UiTextWriter,
ui::widget::TextUiWriter,
window::PresentMode,
};
@ -257,7 +257,7 @@ fn change_text_system(
time: Res<Time>,
diagnostics: Res<DiagnosticsStore>,
query: Query<Entity, With<TextChanges>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
time_history.push_front(time.elapsed());
time_history.truncate(120);

View file

@ -148,7 +148,7 @@ pub(crate) mod test_setup {
mut frame: Local<usize>,
mode: Res<ExampleMode>,
text: Single<Entity, With<ModeText>>,
mut writer: UiTextWriter,
mut writer: TextUiWriter,
) {
*frame += 1;
let mode = match *mode {