UI text layout example (#7359)

## Objective

An example that demonstrates how the `AlignItems` and `JustifyContent` properties can be composed to layout text.

<img width="654" alt="text_layout_example" src="https://user-images.githubusercontent.com/27962798/215116345-daa8ef60-634b-40c6-9b6d-356de3af620c.png">

Cargo.toml

@@ -1526,6 +1526,17 @@ description = "An example for debugging text layout"
 category = "UI (User Interface)"
 wasm = true
 
+[[example]]
+name = "text_layout"
+path = "examples/ui/text_layout.rs"
+
+[package.metadata.example.text_layout]
+name = "Text Layout"
+description = "Demonstrates how the AlignItems and JustifyContent properties can be composed to layout text"
+category = "UI (User Interface)"
+wasm = false
+
+
 [[example]]
 name = "transparency_ui"
 path = "examples/ui/transparency_ui.rs"

examples/README.md

@@ -319,6 +319,7 @@ Example | Description
 [Relative Cursor Position](../examples/ui/relative_cursor_position.rs) | Showcases the RelativeCursorPosition component
 [Text](../examples/ui/text.rs) | Illustrates creating and updating text
 [Text Debug](../examples/ui/text_debug.rs) | An example for debugging text layout
+[Text Layout](../examples/ui/text_layout.rs) | Demonstrates how the AlignItems and JustifyContent properties can be composed to layout text
 [Transparency UI](../examples/ui/transparency_ui.rs) | Demonstrates transparency for UI
 [UI](../examples/ui/ui.rs) | Illustrates various features of Bevy UI
 [UI Scaling](../examples/ui/ui_scaling.rs) | Illustrates how to scale the UI

examples/ui/text_layout.rs

@@ -0,0 +1,184 @@
+//! Demonstrates how the `AlignItems` and `JustifyContent` properties can be composed to layout text.
+use bevy::prelude::*;
+
+const ALIGN_ITEMS_COLOR: Color = Color::rgb(1., 0.066, 0.349);
+const JUSTIFY_CONTENT_COLOR: Color = Color::rgb(0.102, 0.522, 1.);
+const MARGIN: Val = Val::Px(5.);
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins.set(WindowPlugin {
+            primary_window: Some(Window {
+                resolution: [870., 1066.].into(),
+                title: "Bevy Text Layout Example".to_string(),
+                ..Default::default()
+            }),
+            ..Default::default()
+        }))
+        .add_startup_system(spawn_layout)
+        .run();
+}
+
+fn spawn_layout(mut commands: Commands, asset_server: Res<AssetServer>) {
+    let font = asset_server.load("fonts/FiraSans-Bold.ttf");
+    commands.spawn(Camera2dBundle::default());
+    commands
+        .spawn(NodeBundle {
+            style: Style {
+                // fill the entire window
+                size: Size::new(Val::Percent(100.0), Val::Percent(100.0)),
+                flex_direction: FlexDirection::Column,
+                align_items: AlignItems::Center,
+                ..Default::default()
+            },
+            background_color: BackgroundColor(Color::BLACK),
+            ..Default::default()
+        })
+        .with_children(|builder| {
+            // spawn the key
+            builder
+                .spawn(NodeBundle {
+                    style: Style {
+                        flex_direction: FlexDirection::Row,
+                        margin: UiRect::top(MARGIN),
+                        ..Default::default()
+                    },
+                    ..Default::default()
+                })
+                .with_children(|builder| {
+                    spawn_nested_text_bundle(
+                        builder,
+                        font.clone(),
+                        ALIGN_ITEMS_COLOR,
+                        UiRect::right(MARGIN),
+                        "AlignItems",
+                    );
+                    spawn_nested_text_bundle(
+                        builder,
+                        font.clone(),
+                        JUSTIFY_CONTENT_COLOR,
+                        UiRect::default(),
+                        "JustifyContent",
+                    );
+                });
+
+            builder
+                .spawn(NodeBundle {
+                    style: Style {
+                        min_size: Size::new(Val::Px(850.), Val::Px(1020.)),
+                        flex_direction: FlexDirection::Column,
+                        ..Default::default()
+                    },
+                    ..Default::default()
+                })
+                .with_children(|builder| {
+                    // spawn one child node for each combination of `AlignItems` and `JustifyContent`
+                    let justifications = [
+                        JustifyContent::FlexStart,
+                        JustifyContent::Center,
+                        JustifyContent::FlexEnd,
+                        JustifyContent::SpaceEvenly,
+                        JustifyContent::SpaceAround,
+                        JustifyContent::SpaceBetween,
+                    ];
+                    let alignments = [
+                        AlignItems::Baseline,
+                        AlignItems::FlexStart,
+                        AlignItems::Center,
+                        AlignItems::FlexEnd,
+                        AlignItems::Stretch,
+                    ];
+                    for justify_content in justifications {
+                        builder
+                            .spawn(NodeBundle {
+                                style: Style {
+                                    flex_direction: FlexDirection::Row,
+                                    ..Default::default()
+                                },
+                                ..Default::default()
+                            })
+                            .with_children(|builder| {
+                                for align_items in alignments {
+                                    spawn_child_node(
+                                        builder,
+                                        font.clone(),
+                                        align_items,
+                                        justify_content,
+                                    );
+                                }
+                            });
+                    }
+                });
+        });
+}
+
+fn spawn_child_node(
+    builder: &mut ChildBuilder,
+    font: Handle<Font>,
+    align_items: AlignItems,
+    justify_content: JustifyContent,
+) {
+    builder
+        .spawn(NodeBundle {
+            style: Style {
+                flex_direction: FlexDirection::Column,
+                align_items,
+                justify_content,
+                size: Size::new(Val::Px(160.), Val::Px(160.)),
+                margin: UiRect::all(MARGIN),
+                ..Default::default()
+            },
+            background_color: BackgroundColor(Color::DARK_GRAY),
+            ..Default::default()
+        })
+        .with_children(|builder| {
+            let labels = [
+                (format!("{align_items:?}"), ALIGN_ITEMS_COLOR, 0.),
+                (format!("{justify_content:?}"), JUSTIFY_CONTENT_COLOR, 3.),
+            ];
+            for (text, color, top_margin) in labels {
+                // We nest the text within a parent node because margins and padding can't be directly applied to text nodes currently.
+                spawn_nested_text_bundle(
+                    builder,
+                    font.clone(),
+                    color,
+                    UiRect::top(Val::Px(top_margin)),
+                    &text,
+                );
+            }
+        });
+}
+
+fn spawn_nested_text_bundle(
+    builder: &mut ChildBuilder,
+    font: Handle<Font>,
+    background_color: Color,
+    margin: UiRect,
+    text: &str,
+) {
+    builder
+        .spawn(NodeBundle {
+            style: Style {
+                margin,
+                padding: UiRect {
+                    top: Val::Px(1.),
+                    left: Val::Px(5.),
+                    right: Val::Px(5.),
+                    bottom: Val::Px(1.),
+                },
+                ..Default::default()
+            },
+            background_color: BackgroundColor(background_color),
+            ..Default::default()
+        })
+        .with_children(|builder| {
+            builder.spawn(TextBundle::from_section(
+                text,
+                TextStyle {
+                    font,
+                    font_size: 24.0,
+                    color: Color::BLACK,
+                },
+            ));
+        });
+}