Rename TextBlock to TextLayout (#15797)

# Objective

- Improve clarity when spawning a text block. See [this
discussion](#15591).

## Solution

- Rename `TextBlock` to `TextLayout`.

Author: UkoeHB

crates/bevy_text/src/lib.rs

@@ -65,7 +65,7 @@ pub use text_access::*;
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{
-        Font, JustifyText, LineBreak, Text2d, TextBlock, TextError, TextReader2d, TextSpan,
+        Font, JustifyText, LineBreak, Text2d, TextError, TextLayout, TextReader2d, TextSpan,
         TextStyle, TextWriter2d,
     };
 }

crates/bevy_text/src/pipeline.rs

@@ -17,7 +17,7 @@ use cosmic_text::{Attrs, Buffer, Family, Metrics, Shaping, Wrap};
 
 use crate::{
     error::TextError, ComputedTextBlock, Font, FontAtlasSets, FontSmoothing, JustifyText,
-    LineBreak, PositionedGlyph, TextBlock, TextBounds, TextEntity, TextStyle, YAxisOrientation,
+    LineBreak, PositionedGlyph, TextBounds, TextEntity, TextLayout, TextStyle, YAxisOrientation,
 };
 
 /// A wrapper resource around a [`cosmic_text::FontSystem`]
@@ -203,7 +203,7 @@ impl TextPipeline {
         fonts: &Assets<Font>,
         text_spans: impl Iterator<Item = (Entity, usize, &'a str, &'a TextStyle)>,
         scale_factor: f64,
-        block: &TextBlock,
+        layout: &TextLayout,
         bounds: TextBounds,
         font_atlas_sets: &mut FontAtlasSets,
         texture_atlases: &mut Assets<TextureAtlasLayout>,
@@ -229,8 +229,8 @@ impl TextPipeline {
         let update_result = self.update_buffer(
             fonts,
             text_spans,
-            block.linebreak,
-            block.justify,
+            layout.linebreak,
+            layout.justify,
             bounds,
             scale_factor,
             computed,
@@ -337,7 +337,7 @@ impl TextPipeline {
         fonts: &Assets<Font>,
         text_spans: impl Iterator<Item = (Entity, usize, &'a str, &'a TextStyle)>,
         scale_factor: f64,
-        block: &TextBlock,
+        layout: &TextLayout,
         computed: &mut ComputedTextBlock,
         font_system: &mut CosmicFontSystem,
     ) -> Result<TextMeasureInfo, TextError> {
@@ -350,8 +350,8 @@ impl TextPipeline {
         self.update_buffer(
             fonts,
             text_spans,
-            block.linebreak,
-            block.justify,
+            layout.linebreak,
+            layout.justify,
             MIN_WIDTH_CONTENT_BOUNDS,
             scale_factor,
             computed,
@@ -386,7 +386,7 @@ impl TextPipeline {
 /// Render information for a corresponding text block.
 ///
 /// Contains scaled glyphs and their size. Generated via [`TextPipeline::queue_text`] when an entity has
-/// [`TextBlock`] and [`ComputedTextBlock`] components.
+/// [`TextLayout`] and [`ComputedTextBlock`] components.
 #[derive(Component, Clone, Default, Debug, Reflect)]
 #[reflect(Component, Default, Debug)]
 pub struct TextLayoutInfo {

crates/bevy_text/src/text.rs

@@ -25,18 +25,20 @@ impl Default for CosmicBuffer {
     }
 }
 
-/// A sub-entity of a [`TextBlock`].
+/// A sub-entity of a [`ComputedTextBlock`].
 ///
 /// Returned by [`ComputedTextBlock::entities`].
 #[derive(Debug, Copy, Clone)]
 pub struct TextEntity {
     /// The entity.
     pub entity: Entity,
-    /// Records the hierarchy depth of the entity within a `TextBlock`.
+    /// Records the hierarchy depth of the entity within a `TextLayout`.
     pub depth: usize,
 }
 
-/// Computed information for a [`TextBlock`].
+/// Computed information for a text block.
+///
+/// See [`TextLayout`].
 ///
 /// Automatically updated by 2d and UI text systems.
 #[derive(Component, Debug, Clone)]
@@ -45,7 +47,7 @@ pub struct ComputedTextBlock {
     ///
     /// This is private because buffer contents are always refreshed from ECS state when writing glyphs to
     /// `TextLayoutInfo`. If you want to control the buffer contents manually or use the `cosmic-text`
-    /// editor, then you need to not use `TextBlock` and instead manually implement the conversion to
+    /// editor, then you need to not use `TextLayout` and instead manually implement the conversion to
     /// `TextLayoutInfo`.
     pub(crate) buffer: CosmicBuffer,
     /// Entities for all text spans in the block, including the root-level text.
@@ -55,12 +57,12 @@ pub struct ComputedTextBlock {
     /// Flag set when any change has been made to this block that should cause it to be rerendered.
     ///
     /// Includes:
-    /// - [`TextBlock`] changes.
+    /// - [`TextLayout`] changes.
     /// - [`TextStyle`] or `Text2d`/`Text`/`TextSpan` changes anywhere in the block's entity hierarchy.
     // TODO: This encompasses both structural changes like font size or justification and non-structural
     // changes like text color and font smoothing. This field currently causes UI to 'remeasure' text, even if
     // the actual changes are non-structural and can be handled by only rerendering and not remeasuring. A full
-    // solution would probably require splitting TextBlock and TextStyle into structural/non-structural
+    // solution would probably require splitting TextLayout and TextStyle into structural/non-structural
     // components for more granular change detection. A cost/benefit analysis is needed.
     pub(crate) needs_rerender: bool,
 }
@@ -103,57 +105,57 @@ impl Default for ComputedTextBlock {
 #[derive(Component, Debug, Copy, Clone, Default, Reflect)]
 #[reflect(Component, Default, Debug)]
 #[require(ComputedTextBlock, TextLayoutInfo)]
-pub struct TextBlock {
+pub struct TextLayout {
     /// The text's internal alignment.
     /// Should not affect its position within a container.
     pub justify: JustifyText,
     /// How the text should linebreak when running out of the bounds determined by `max_size`.
     pub linebreak: LineBreak,
 }
 
-impl TextBlock {
-    /// Makes a new [`TextBlock`].
+impl TextLayout {
+    /// Makes a new [`TextLayout`].
     pub const fn new(justify: JustifyText, linebreak: LineBreak) -> Self {
         Self { justify, linebreak }
     }
 
-    /// Makes a new [`TextBlock`] with the specified [`JustifyText`].
+    /// Makes a new [`TextLayout`] with the specified [`JustifyText`].
     pub fn new_with_justify(justify: JustifyText) -> Self {
         Self::default().with_justify(justify)
     }
 
-    /// Makes a new [`TextBlock`] with the specified [`LineBreak`].
+    /// Makes a new [`TextLayout`] with the specified [`LineBreak`].
     pub fn new_with_linebreak(linebreak: LineBreak) -> Self {
         Self::default().with_linebreak(linebreak)
     }
 
-    /// Makes a new [`TextBlock`] with soft wrapping disabled.
+    /// Makes a new [`TextLayout`] with soft wrapping disabled.
     /// Hard wrapping, where text contains an explicit linebreak such as the escape sequence `\n`, will still occur.
     pub fn new_with_no_wrap() -> Self {
         Self::default().with_no_wrap()
     }
 
-    /// Returns this [`TextBlock`] with the specified [`JustifyText`].
+    /// Returns this [`TextLayout`] with the specified [`JustifyText`].
     pub const fn with_justify(mut self, justify: JustifyText) -> Self {
         self.justify = justify;
         self
     }
 
-    /// Returns this [`TextBlock`] with the specified [`LineBreak`].
+    /// Returns this [`TextLayout`] with the specified [`LineBreak`].
     pub const fn with_linebreak(mut self, linebreak: LineBreak) -> Self {
         self.linebreak = linebreak;
         self
     }
 
-    /// Returns this [`TextBlock`] with soft wrapping disabled.
+    /// Returns this [`TextLayout`] with soft wrapping disabled.
     /// Hard wrapping, where text contains an explicit linebreak such as the escape sequence `\n`, will still occur.
     pub const fn with_no_wrap(mut self) -> Self {
         self.linebreak = LineBreak::NoWrap;
         self
     }
 }
 
-/// A span of UI text in a tree of spans under an entity with [`TextBlock`], such as `Text` or `Text2d`.
+/// A span of UI text in a tree of spans under an entity with [`TextLayout`] and `Text` or `Text2d`.
 ///
 /// Spans are collected in hierarchy traversal order into a [`ComputedTextBlock`] for layout.
 ///
@@ -163,13 +165,13 @@ impl TextBlock {
 # use bevy_color::Color;
 # use bevy_color::palettes::basic::{RED, BLUE};
 # use bevy_ecs::World;
-# use bevy_text::{Font, TextBlock, TextStyle, TextSection};
+# use bevy_text::{Font, TextLayout, TextStyle, TextSection};
 
 # let font_handle: Handle<Font> = Default::default();
 # let mut world = World::default();
 #
 world.spawn((
-    TextBlock::default(),
+    TextLayout::default(),
     TextStyle {
         font: font_handle.clone().into(),
         font_size: 60.0,
@@ -257,7 +259,7 @@ impl From<JustifyText> for cosmic_text::Align {
     }
 }
 
-/// `TextStyle` determines the style of a text span within a [`TextBlock`], specifically
+/// `TextStyle` determines the style of a text span within a [`ComputedTextBlock`], specifically
 /// the font face, the font size, and the color.
 #[derive(Component, Clone, Debug, Reflect)]
 #[reflect(Component, Default, Debug)]
@@ -285,7 +287,7 @@ pub struct TextStyle {
 }
 
 impl TextStyle {
-    /// Returns this [`TextBlock`] with the specified [`FontSmoothing`].
+    /// Returns this [`TextStyle`] with the specified [`FontSmoothing`].
     pub const fn with_font_smoothing(mut self, font_smoothing: FontSmoothing) -> Self {
         self.font_smoothing = font_smoothing;
         self
@@ -358,23 +360,23 @@ pub fn detect_text_needs_rerender<Root: Component>(
             Or<(
                 Changed<Root>,
                 Changed<TextStyle>,
-                Changed<TextBlock>,
+                Changed<TextLayout>,
                 Changed<Children>,
             )>,
             With<Root>,
             With<TextStyle>,
-            With<TextBlock>,
+            With<TextLayout>,
         ),
     >,
     changed_spans: Query<
-        (Entity, Option<&Parent>, Has<TextBlock>),
+        (Entity, Option<&Parent>, Has<TextLayout>),
         (
             Or<(
                 Changed<TextSpan>,
                 Changed<TextStyle>,
                 Changed<Children>,
                 Changed<Parent>, // Included to detect broken text block hierarchies.
-                Added<TextBlock>,
+                Added<TextLayout>,
             )>,
             With<TextSpan>,
             With<TextStyle>,
@@ -389,7 +391,7 @@ pub fn detect_text_needs_rerender<Root: Component>(
     // Root entity:
     // - Root component changed.
     // - TextStyle on root changed.
-    // - TextBlock changed.
+    // - TextLayout changed.
     // - Root children changed (can include additions and removals).
     for root in changed_roots.iter() {
         let Ok((_, Some(mut computed), _)) = computed.get_mut(root) else {
@@ -406,7 +408,7 @@ pub fn detect_text_needs_rerender<Root: Component>(
     // - Span children changed (can include additions and removals).
     for (entity, maybe_span_parent, has_text_block) in changed_spans.iter() {
         if has_text_block {
-            warn_once!("found entity {:?} with a TextSpan that has a TextBlock, which should only be on root \
+            warn_once!("found entity {:?} with a TextSpan that has a TextLayout, which should only be on root \
                 text entities (that have {}); this warning only prints once",
                 entity, core::any::type_name::<Root>());
         }

crates/bevy_text/src/text2d.rs

@@ -1,7 +1,7 @@
 use crate::pipeline::CosmicFontSystem;
 use crate::{
-    ComputedTextBlock, Font, FontAtlasSets, LineBreak, PositionedGlyph, SwashCache, TextBlock,
-    TextBounds, TextError, TextLayoutInfo, TextPipeline, TextReader, TextRoot, TextSpanAccess,
+    ComputedTextBlock, Font, FontAtlasSets, LineBreak, PositionedGlyph, SwashCache, TextBounds,
+    TextError, TextLayout, TextLayoutInfo, TextPipeline, TextReader, TextRoot, TextSpanAccess,
     TextStyle, TextWriter, YAxisOrientation,
 };
 use bevy_asset::Assets;
@@ -38,9 +38,9 @@ use bevy_window::{PrimaryWindow, Window, WindowScaleFactorChanged};
 /// [Example usage.](https://github.com/bevyengine/bevy/blob/latest/examples/2d/text2d.rs)
 ///
 /// The string in this component is the first 'text span' in a hierarchy of text spans that are collected into
-/// a [`TextBlock`]. See [`TextSpan`](crate::TextSpan) for the component used by children of entities with [`Text2d`].
+/// a [`ComputedTextBlock`]. See [`TextSpan`](crate::TextSpan) for the component used by children of entities with [`Text2d`].
 ///
-/// With `Text2d` the `justify` field of [`TextBlock`] only affects the internal alignment of a block of text and not its
+/// With `Text2d` the `justify` field of [`TextLayout`] only affects the internal alignment of a block of text and not its
 /// relative position, which is controlled by the [`Anchor`] component.
 /// This means that for a block of text consisting of only one line that doesn't wrap, the `justify` field will have no effect.
 ///
@@ -50,7 +50,7 @@ use bevy_window::{PrimaryWindow, Window, WindowScaleFactorChanged};
 # use bevy_color::Color;
 # use bevy_color::palettes::basic::BLUE;
 # use bevy_ecs::World;
-# use bevy_text::{Font, JustifyText, Text2d, TextBlock, TextStyle};
+# use bevy_text::{Font, JustifyText, Text2d, TextLayout, TextStyle};
 #
 # let font_handle: Handle<Font> = Default::default();
 # let mut world = World::default();
@@ -71,14 +71,14 @@ world.spawn((
 // With text justification.
 world.spawn((
     Text2d::new("hello world\nand bevy!"),
-    TextBlock::new_with_justify(JustifyText::Center)
+    TextLayout::new_with_justify(JustifyText::Center)
 ));
 ```
 */
 #[derive(Component, Clone, Debug, Default, Deref, DerefMut, Reflect)]
 #[reflect(Component, Default, Debug)]
 #[require(
-    TextBlock,
+    TextLayout,
     TextStyle,
     TextBounds,
     Anchor,
@@ -230,7 +230,7 @@ pub fn update_text2d_layout(
     mut text_pipeline: ResMut<TextPipeline>,
     mut text_query: Query<(
         Entity,
-        Ref<TextBlock>,
+        Ref<TextLayout>,
         Ref<TextBounds>,
         &mut TextLayoutInfo,
         &mut ComputedTextBlock,

crates/bevy_text/src/text_access.rs

@@ -42,7 +42,7 @@ impl TextIterScratch {
     }
 }
 
-/// System parameter for reading text spans in a [`TextBlock`](crate::TextBlock).
+/// 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.
 #[derive(SystemParam)]
@@ -184,7 +184,7 @@ impl<'a, R: TextRoot> Drop for TextSpanIter<'a, R> {
     }
 }
 
-/// System parameter for reading and writing text spans in a [`TextBlock`](crate::TextBlock).
+/// System parameter for reading and writing text spans in a text block.
 ///
 /// `R` is the root text component, and `S` is the text span component on children.
 #[derive(SystemParam)]