From e9a0d6ccc53846098607d5a6725499e8e66045b1 Mon Sep 17 00:00:00 2001 From: CrumbsTrace <45168144+CrumbsTrace@users.noreply.github.com> Date: Sun, 29 Oct 2023 16:32:11 +0100 Subject: [PATCH] Update UI alignment docs (#10303) # Objective - Address inconsistent term usage in the docs for the alignment properties for UI nodes. Fixes #10218 - `JustifyContent::Stretch` is missing despite being supported by Taffy, being as the default value for Grids, so it should be added to Bevy as well ## Solution - Consistently provide links to the mdn site for the css equivalent - Match (mostly) the documentation given on the pub struct and the underlying enums - Use the term `items` consistently to refer each child in the container - Add `JustifyContent::Stretch` and map it to Taffy ## Migration Guide - The `JustifyContents` enum has been expanded to include `JustifyContents::Stretch`. --- crates/bevy_ui/src/layout/convert.rs | 1 + crates/bevy_ui/src/ui_node.rs | 131 ++++++++++++++++----------- 2 files changed, 81 insertions(+), 51 deletions(-) diff --git a/crates/bevy_ui/src/layout/convert.rs b/crates/bevy_ui/src/layout/convert.rs index fcb164052e089..57882b1fe326e 100644 --- a/crates/bevy_ui/src/layout/convert.rs +++ b/crates/bevy_ui/src/layout/convert.rs @@ -218,6 +218,7 @@ impl From for Option { JustifyContent::FlexStart => taffy::style::JustifyContent::FlexStart.into(), JustifyContent::FlexEnd => taffy::style::JustifyContent::FlexEnd.into(), JustifyContent::Center => taffy::style::JustifyContent::Center.into(), + JustifyContent::Stretch => taffy::style::JustifyContent::Stretch.into(), JustifyContent::SpaceBetween => taffy::style::JustifyContent::SpaceBetween.into(), JustifyContent::SpaceAround => taffy::style::JustifyContent::SpaceAround.into(), JustifyContent::SpaceEvenly => taffy::style::JustifyContent::SpaceEvenly.into(), diff --git a/crates/bevy_ui/src/ui_node.rs b/crates/bevy_ui/src/ui_node.rs index 81769141d4c17..12400668400a3 100644 --- a/crates/bevy_ui/src/ui_node.rs +++ b/crates/bevy_ui/src/ui_node.rs @@ -216,7 +216,8 @@ pub struct Style { /// pub aspect_ratio: Option, - /// - For Flexbox containers, sets default cross-axis alignment of the child items. + /// Used to control how each individual item is aligned by default within the space they're given. + /// - For Flexbox containers, sets default cross axis alignment of the child items. /// - For CSS Grid containers, controls block (vertical) axis alignment of children of this grid container within their grid areas. /// /// This value is overridden if [`AlignSelf`] on the child node is set. @@ -224,7 +225,8 @@ pub struct Style { /// pub align_items: AlignItems, - /// - For Flexbox containers, this property has no effect. See `justify_content` for main-axis alignment of flex items. + /// Used to control how each individual item is aligned by default within the space they're given. + /// - For Flexbox containers, this property has no effect. See `justify_content` for main axis alignment of flex items. /// - For CSS Grid containers, sets default inline (horizontal) axis alignment of child items within their grid areas. /// /// This value is overridden if [`JustifySelf`] on the child node is set. @@ -232,7 +234,8 @@ pub struct Style { /// pub justify_items: JustifyItems, - /// - For Flexbox items, controls cross-axis alignment of the item. + /// Used to control how the specified item is aligned within the space it's given. + /// - For Flexbox items, controls cross axis alignment of the item. /// - For CSS Grid items, controls block (vertical) axis alignment of a grid item within its grid area. /// /// If set to `Auto`, alignment is inherited from the value of [`AlignItems`] set on the parent node. @@ -240,7 +243,8 @@ pub struct Style { /// pub align_self: AlignSelf, - /// - For Flexbox items, this property has no effect. See `justify_content` for main-axis alignment of flex items. + /// Used to control how the specified item is aligned within the space it's given. + /// - For Flexbox items, this property has no effect. See `justify_content` for main axis alignment of flex items. /// - For CSS Grid items, controls inline (horizontal) axis alignment of a grid item within its grid area. /// /// If set to `Auto`, alignment is inherited from the value of [`JustifyItems`] set on the parent node. @@ -248,12 +252,14 @@ pub struct Style { /// pub justify_self: JustifySelf, - /// - For Flexbox containers, controls alignment of lines if flex_wrap is set to [`FlexWrap::Wrap`] and there are multiple lines of items. + /// Used to control how items are distributed. + /// - For Flexbox containers, controls alignment of lines if `flex_wrap` is set to [`FlexWrap::Wrap`] and there are multiple lines of items. /// - For CSS Grid containers, controls alignment of grid rows. /// /// pub align_content: AlignContent, + /// Used to control how items are distributed. /// - For Flexbox containers, controls alignment of items in the main axis. /// - For CSS Grid containers, controls alignment of grid columns. /// @@ -443,27 +449,31 @@ impl Default for Style { } } -/// How items are aligned according to the cross axis +/// Used to control how each individual item is aligned by default within the space they're given. +/// - For Flexbox containers, sets default cross axis alignment of the child items. +/// - For CSS Grid containers, controls block (vertical) axis alignment of children of this grid container within their grid areas. +/// +/// #[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub enum AlignItems { /// The items are packed in their default position as if no alignment was applied. Default, - /// Items are packed towards the start of the axis. + /// The items are packed towards the start of the axis. Start, - /// Items are packed towards the end of the axis. + /// The items are packed towards the end of the axis. End, - /// Items are packed towards the start of the axis, unless the flex direction is reversed; + /// The items are packed towards the start of the axis, unless the flex direction is reversed; /// then they are packed towards the end of the axis. FlexStart, - /// Items are packed towards the end of the axis, unless the flex direction is reversed; + /// The items are packed towards the end of the axis, unless the flex direction is reversed; /// then they are packed towards the start of the axis. FlexEnd, - /// Items are aligned at the center. + /// The items are packed along the center of the axis. Center, - /// Items are aligned at the baseline. + /// The items are packed such that their baselines align. Baseline, - /// Items are stretched across the whole cross axis. + /// The items are stretched to fill the space they're given. Stretch, } @@ -477,21 +487,25 @@ impl Default for AlignItems { } } -/// How items are aligned according to the main axis +/// Used to control how each individual item is aligned by default within the space they're given. +/// - For Flexbox containers, this property has no effect. See `justify_content` for main axis alignment of flex items. +/// - For CSS Grid containers, sets default inline (horizontal) axis alignment of child items within their grid areas. +/// +/// #[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub enum JustifyItems { /// The items are packed in their default position as if no alignment was applied. Default, - /// Items are packed towards the start of the axis. + /// The items are packed towards the start of the axis. Start, - /// Items are packed towards the end of the axis. + /// The items are packed towards the end of the axis. End, - /// Items are aligned at the center. + /// The items are packed along the center of the axis Center, - /// Items are aligned at the baseline. + /// The items are packed such that their baselines align. Baseline, - /// Items are stretched across the whole main axis. + /// The items are stretched to fill the space they're given. Stretch, } @@ -505,8 +519,11 @@ impl Default for JustifyItems { } } -/// How this item is aligned according to the cross axis. -/// Overrides [`AlignItems`]. +/// Used to control how the specified item is aligned within the space it's given. +/// - For Flexbox items, controls cross axis alignment of the item. +/// - For CSS Grid items, controls block (vertical) axis alignment of a grid item within its grid area. +/// +/// #[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub enum AlignSelf { @@ -522,11 +539,11 @@ pub enum AlignSelf { /// This item will be aligned with the end of the axis, unless the flex direction is reversed; /// then it will be aligned with the start of the axis. FlexEnd, - /// This item will be aligned at the center. + /// This item will be aligned along the center of the axis. Center, /// This item will be aligned at the baseline. Baseline, - /// This item will be stretched across the whole cross axis. + /// This item will be stretched to fill the container. Stretch, } @@ -540,8 +557,11 @@ impl Default for AlignSelf { } } -/// How this item is aligned according to the main axis. -/// Overrides [`JustifyItems`]. +/// Used to control how the specified item is aligned within the space it's given. +/// - For Flexbox items, this property has no effect. See `justify_content` for main axis alignment of flex items. +/// - For CSS Grid items, controls inline (horizontal) axis alignment of a grid item within its grid area. +/// +/// #[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub enum JustifySelf { @@ -551,11 +571,11 @@ pub enum JustifySelf { Start, /// This item will be aligned with the end of the axis. End, - /// This item will be aligned at the center. + /// This item will be aligned along the center of the axis. Center, /// This item will be aligned at the baseline. Baseline, - /// This item will be stretched across the whole main axis. + /// This item will be stretched to fill the space it's given. Stretch, } @@ -569,34 +589,35 @@ impl Default for JustifySelf { } } -/// Defines how each line is aligned within the flexbox. +/// Used to control how items are distributed. +/// - For Flexbox containers, controls alignment of lines if `flex_wrap` is set to [`FlexWrap::Wrap`] and there are multiple lines of items. +/// - For CSS Grid containers, controls alignment of grid rows. /// -/// It only applies if [`FlexWrap::Wrap`] is present and if there are multiple lines of items. +/// #[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub enum AlignContent { /// The items are packed in their default position as if no alignment was applied. Default, - /// Each line moves towards the start of the cross axis. + /// The items are packed towards the start of the axis. Start, - /// Each line moves towards the end of the cross axis. + /// The items are packed towards the end of the axis. End, - /// Each line moves towards the start of the cross axis, unless the flex direction is reversed; then the line moves towards the end of the cross axis. + /// The items are packed towards the start of the axis, unless the flex direction is reversed; + /// then the items are packed towards the end of the axis. FlexStart, - /// Each line moves towards the end of the cross axis, unless the flex direction is reversed; then the line moves towards the start of the cross axis. + /// The items are packed towards the end of the axis, unless the flex direction is reversed; + /// then the items are packed towards the start of the axis. FlexEnd, - /// Each line moves towards the center of the cross axis. + /// The items are packed along the center of the axis. Center, - /// Each line will stretch to fill the remaining space. + /// The items are stretched to fill the container along the axis. Stretch, - /// Each line fills the space it needs, putting the remaining space, if any, - /// between the lines. + /// The items are distributed such that the gap between any two items is equal. SpaceBetween, - /// The gap between the first and last items is exactly the same as the gap between items. - /// The gaps are distributed evenly. + /// The items are distributed such that the gap between and around any two items is equal. SpaceEvenly, - /// Each line fills the space it needs, putting the remaining space, if any, - /// around the lines. + /// The items are distributed such that the gap between and around any two items is equal, with half-size gaps on either end. SpaceAround, } @@ -610,28 +631,36 @@ impl Default for AlignContent { } } -/// Defines how items are aligned according to the main axis +/// Used to control how items are distributed. +/// - For Flexbox containers, controls alignment of items in the main axis. +/// - For CSS Grid containers, controls alignment of grid columns. +/// +/// #[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub enum JustifyContent { /// The items are packed in their default position as if no alignment was applied. Default, - /// Items are packed toward the start of the axis. + /// The items are packed towards the start of the axis. Start, - /// Items are packed toward the end of the axis. + /// The items are packed towards the end of the axis. End, - /// Pushed towards the start, unless the flex direction is reversed; then pushed towards the end. + /// The items are packed towards the start of the axis, unless the flex direction is reversed; + /// then the items are packed towards the end of the axis. FlexStart, - /// Pushed towards the end, unless the flex direction is reversed; then pushed towards the start. + /// The items are packed towards the end of the axis, unless the flex direction is reversed; + /// then the items are packed towards the start of the axis. FlexEnd, - /// Centered along the main axis. + /// The items are packed along the center of the axis. Center, - /// Remaining space is distributed between the items. + /// The items are stretched to fill the container along the axis. + Stretch, + /// The items are distributed such that the gap between any two items is equal. SpaceBetween, - /// Remaining space is distributed around the items. - SpaceAround, - /// Like [`JustifyContent::SpaceAround`] but with even spacing between items. + /// The items are distributed such that the gap between and around any two items is equal. SpaceEvenly, + /// The items are distributed such that the gap between and around any two items is equal, with half-size gaps on either end. + SpaceAround, } impl JustifyContent {