diff --git a/crates/bevy_ui/src/ui_node.rs b/crates/bevy_ui/src/ui_node.rs index 3a87765fea..81769141d4 100644 --- a/crates/bevy_ui/src/ui_node.rs +++ b/crates/bevy_ui/src/ui_node.rs @@ -14,29 +14,34 @@ use thiserror::Error; #[derive(Component, Debug, Copy, Clone, Reflect)] #[reflect(Component, Default)] pub struct Node { - /// The size of the node as width and height in logical pixels - /// automatically calculated by [`super::layout::ui_layout_system`] + /// The size of the node as width and height in logical pixels. + /// + /// Automatically calculated by [`super::layout::ui_layout_system`]. pub(crate) calculated_size: Vec2, - /// The width of this node's outline - /// If this value is `Auto`, negative or `0.` then no outline will be rendered - /// automatically calculated by [`super::layout::resolve_outlines_system`] + /// The width of this node's outline. + /// If this value is `Auto`, negative or `0.` then no outline will be rendered. + /// + /// Automatically calculated by [`super::layout::resolve_outlines_system`]. pub(crate) outline_width: f32, - // The amount of space between the outline and the edge of the node + /// The amount of space between the outline and the edge of the node. pub(crate) outline_offset: f32, - /// The unrounded size of the node as width and height in logical pixels - /// automatically calculated by [`super::layout::ui_layout_system`] + /// The unrounded size of the node as width and height in logical pixels. + /// + /// Automatically calculated by [`super::layout::ui_layout_system`]. pub(crate) unrounded_size: Vec2, } impl Node { - /// The calculated node size as width and height in logical pixels - /// automatically calculated by [`super::layout::ui_layout_system`] + /// The calculated node size as width and height in logical pixels. + /// + /// Automatically calculated by [`super::layout::ui_layout_system`]. pub const fn size(&self) -> Vec2 { self.calculated_size } - /// The calculated node size as width and height in logical pixels before rounding - /// automatically calculated by [`super::layout::ui_layout_system`] + /// The calculated node size as width and height in logical pixels before rounding. + /// + /// Automatically calculated by [`super::layout::ui_layout_system`]. pub const fn unrounded_size(&self) -> Vec2 { self.unrounded_size } @@ -102,7 +107,8 @@ impl Default for Node { /// Describes the style of a UI container node /// -/// Node's can be laid out using either Flexbox or CSS Grid Layout.
+/// Nodes can be laid out using either Flexbox or CSS Grid Layout. +/// /// See below for general learning resources and for documentation on the individual style properties. /// /// ### Flexbox @@ -128,7 +134,7 @@ pub struct Style { /// pub display: Display, - /// Whether a node should be laid out in-flow with, or independently of it's siblings: + /// Whether a node should be laid out in-flow with, or independently of its siblings: /// - [`PositionType::Relative`]: Layout this node in-flow with other nodes using the usual (flexbox/grid) layout algorithm. /// - [`PositionType::Absolute`]: Layout this node on top and independently of other nodes. /// @@ -140,9 +146,10 @@ pub struct Style { /// pub overflow: Overflow, - /// Defines the text direction. For example English is written LTR (left-to-right) while Arabic is written RTL (right-to-left). + /// Defines the text direction. For example, English is written LTR (left-to-right) while Arabic is written RTL (right-to-left). + /// + /// Note: the corresponding CSS property also affects box layout order, but this isn't yet implemented in Bevy. /// - /// Note: the corresponding CSS property also affects box layout order, but this isn't yet implemented in bevy. /// pub direction: Direction, @@ -184,12 +191,12 @@ pub struct Style { /// pub height: Val, - /// The minimum width of the node. `min_width` is used if it is greater than either `width` and/or `max_width`. + /// The minimum width of the node. `min_width` is used if it is greater than `width` and/or `max_width`. /// /// pub min_width: Val, - /// The minimum height of the node. `min_height` is used if it is greater than either `height` and/or `max_height`. + /// The minimum height of the node. `min_height` is used if it is greater than `height` and/or `max_height`. /// /// pub min_height: Val, @@ -226,7 +233,7 @@ pub struct Style { pub justify_items: JustifyItems, /// - For Flexbox items, controls cross-axis alignment of the item. - /// - For CSS Grid items, controls block (vertical) axis alignment of a grid item within it's grid area. + /// - 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. /// @@ -234,11 +241,11 @@ 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. - /// - For CSS Grid items, controls inline (horizontal) axis alignment of a grid item within it's grid area. + /// - 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. /// - /// + /// 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. @@ -270,7 +277,7 @@ pub struct Style { /// ..Default::default() /// }; /// ``` - /// A node with this style and a parent with dimensions of 100px by 300px, will have calculated margins of 10px on both left and right edges, and 15px on both top and bottom edges. + /// A node with this style and a parent with dimensions of 100px by 300px will have calculated margins of 10px on both left and right edges, and 15px on both top and bottom edges. /// /// pub margin: UiRect, @@ -292,7 +299,7 @@ pub struct Style { /// ..Default::default() /// }; /// ``` - /// A node with this style and a parent with dimensions of 300px by 100px, will have calculated padding of 3px on the left, 6px on the right, 9px on the top and 12px on the bottom. + /// A node with this style and a parent with dimensions of 300px by 100px will have calculated padding of 3px on the left, 6px on the right, 9px on the top and 12px on the bottom. /// /// pub padding: UiRect, @@ -306,12 +313,12 @@ pub struct Style { /// pub border: UiRect, - /// Whether a Flexbox container should be a row or a column. This property has no effect of Grid nodes. + /// Whether a Flexbox container should be a row or a column. This property has no effect on Grid nodes. /// /// pub flex_direction: FlexDirection, - /// Whether a Flexbox container should wrap it's contents onto multiple line wrap if they overflow. This property has no effect of Grid nodes. + /// Whether a Flexbox container should wrap its contents onto multiple lines if they overflow. This property has no effect on Grid nodes. /// /// pub flex_wrap: FlexWrap, @@ -328,27 +335,27 @@ pub struct Style { /// The initial length of a flexbox in the main axis, before flex growing/shrinking properties are applied. /// - /// `flex_basis` overrides `size` on the main axis if both are set, but it obeys the bounds defined by `min_size` and `max_size`. + /// `flex_basis` overrides `size` on the main axis if both are set, but it obeys the bounds defined by `min_size` and `max_size`. /// /// pub flex_basis: Val, - /// The size of the gutters between items in a vertical flexbox layout or between rows in a grid layout + /// The size of the gutters between items in a vertical flexbox layout or between rows in a grid layout. /// /// Note: Values of `Val::Auto` are not valid and are treated as zero. /// /// pub row_gap: Val, - /// The size of the gutters between items in a horizontal flexbox layout or between column in a grid layout + /// The size of the gutters between items in a horizontal flexbox layout or between column in a grid layout. /// /// Note: Values of `Val::Auto` are not valid and are treated as zero. /// /// pub column_gap: Val, - /// Controls whether automatically placed grid items are placed row-wise or column-wise. And whether the sparse or dense packing algorithm is used. - /// Only affect Grid layouts + /// Controls whether automatically placed grid items are placed row-wise or column-wise as well as whether the sparse or dense packing algorithm is used. + /// Only affects Grid layouts. /// /// pub grid_auto_flow: GridAutoFlow, @@ -373,7 +380,7 @@ pub struct Style { /// Defines the size of implicitly created columns. Columns are created implicitly when grid items are given explicit placements that are out of bounds /// of the columns explicitly created using `grid_template_columns`. /// - /// + /// pub grid_auto_columns: Vec, /// The row in which a grid item starts and how many rows it spans. @@ -440,7 +447,7 @@ impl Default for Style { #[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 + /// The items are packed in their default position as if no alignment was applied. Default, /// Items are packed towards the start of the axis. Start, @@ -474,7 +481,7 @@ impl Default for AlignItems { #[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 + /// The items are packed in their default position as if no alignment was applied. Default, /// Items are packed towards the start of the axis. Start, @@ -568,7 +575,7 @@ impl Default for JustifySelf { #[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 + /// 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. Start, @@ -582,13 +589,13 @@ pub enum AlignContent { Center, /// Each line will stretch to fill the remaining space. Stretch, - /// Each line fills the space it needs, putting the remaining space, if any - /// inbetween the lines. + /// Each line fills the space it needs, putting the remaining space, if any, + /// between the lines. SpaceBetween, - /// The gap between the first and last items is exactly THE SAME as the gap between items. + /// The gap between the first and last items is exactly the same as the gap between items. /// The gaps are distributed evenly. SpaceEvenly, - /// Each line fills the space it needs, putting the remaining space, if any + /// Each line fills the space it needs, putting the remaining space, if any, /// around the lines. SpaceAround, } @@ -607,7 +614,7 @@ impl Default for AlignContent { #[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 + /// The items are packed in their default position as if no alignment was applied. Default, /// Items are packed toward the start of the axis. Start, @@ -637,9 +644,9 @@ impl Default for JustifyContent { } } -/// Defines the text direction +/// Defines the text direction. /// -/// For example English is written LTR (left-to-right) while Arabic is written RTL (right-to-left). +/// For example, English is written LTR (left-to-right) while Arabic is written RTL (right-to-left). #[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub enum Direction { @@ -661,7 +668,7 @@ impl Default for Direction { } } -/// Whether to use a Flexbox layout model. +/// Defines the layout model used by this node. /// /// Part of the [`Style`] component. #[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)] @@ -803,9 +810,7 @@ impl Default for OverflowAxis { pub enum PositionType { /// Relative to all other nodes with the [`PositionType::Relative`] value. Relative, - /// Independent of all other nodes. - /// - /// As usual, the `Style.position` field of this node is specified relative to its parent node. + /// Independent of all other nodes, but relative to its parent node. Absolute, } @@ -841,17 +846,18 @@ impl Default for FlexWrap { } } -/// Controls whether grid items are placed row-wise or column-wise. And whether the sparse or dense packing algorithm is used. +/// Controls whether grid items are placed row-wise or column-wise as well as whether the sparse or dense packing algorithm is used. /// -/// The "dense" packing algorithm attempts to fill in holes earlier in the grid, if smaller items come up later. This may cause items to appear out-of-order, when doing so would fill in holes left by larger items. +/// The "dense" packing algorithm attempts to fill in holes earlier in the grid, if smaller items come up later. +/// This may cause items to appear out-of-order when doing so would fill in holes left by larger items. /// -/// Defaults to [`GridAutoFlow::Row`] +/// Defaults to [`GridAutoFlow::Row`]. /// /// #[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] pub enum GridAutoFlow { - /// Items are placed by filling each row in turn, adding new rows as necessary + /// Items are placed by filling each row in turn, adding new rows as necessary. Row, /// Items are placed by filling each column in turn, adding new columns as necessary. Column, @@ -904,7 +910,8 @@ pub enum MaxTrackSizingFunction { /// Track maximum size should be automatically sized Auto, /// The dimension as a fraction of the total available grid space (`fr` units in CSS) - /// Specified value is the numerator of the fraction. Denominator is the sum of all fractions specified in that grid dimension + /// Specified value is the numerator of the fraction. Denominator is the sum of all fractions specified in that grid dimension. + /// /// Spec: Fraction(f32), } @@ -944,7 +951,7 @@ impl GridTrack { /// Create a grid track with an `fr` size. /// Note that this will give the track a content-based minimum size. - /// Usually you are best off using `GridTrack::flex` instead which uses a zero minimum size + /// Usually you are best off using `GridTrack::flex` instead which uses a zero minimum size. pub fn fr>(value: f32) -> T { Self { min_sizing_function: MinTrackSizingFunction::Auto, @@ -953,7 +960,7 @@ impl GridTrack { .into() } - /// Create a grid track with an `minmax(0, Nfr)` size. + /// Create a grid track with a `minmax(0, Nfr)` size. pub fn flex>(value: f32) -> T { Self { min_sizing_function: MinTrackSizingFunction::Px(0.0), @@ -962,7 +969,7 @@ impl GridTrack { .into() } - /// Create a grid track which is automatically sized to fit it's contents, and then + /// Create a grid track which is automatically sized to fit its contents. pub fn auto>() -> T { Self { min_sizing_function: MinTrackSizingFunction::Auto, @@ -971,7 +978,7 @@ impl GridTrack { .into() } - /// Create a grid track which is automatically sized to fit it's contents when sized at their "min-content" sizes + /// Create a grid track which is automatically sized to fit its contents when sized at their "min-content" sizes pub fn min_content>() -> T { Self { min_sizing_function: MinTrackSizingFunction::MinContent, @@ -980,7 +987,7 @@ impl GridTrack { .into() } - /// Create a grid track which is automatically sized to fit it's contents when sized at their "max-content" sizes + /// Create a grid track which is automatically sized to fit its contents when sized at their "max-content" sizes pub fn max_content>() -> T { Self { min_sizing_function: MinTrackSizingFunction::MaxContent, @@ -1070,14 +1077,14 @@ impl From for GridTrackRepetition { /// /// The repetition parameter can either be: /// - The integer `1`, in which case the track is non-repeated. -/// - a `u16` count to repeat the track N times -/// - A `GridTrackRepetition::AutoFit` or `GridTrackRepetition::AutoFill` +/// - a `u16` count to repeat the track N times. +/// - A `GridTrackRepetition::AutoFit` or `GridTrackRepetition::AutoFill`. /// /// Note: that in the common case you want a non-repeating track (repetition count 1), you may use the constructor methods on [`GridTrack`] /// to create a `RepeatedGridTrack`. i.e. `GridTrack::px(10.0)` is equivalent to `RepeatedGridTrack::px(1, 10.0)`. /// /// You may only use one auto-repetition per track list. And if your track list contains an auto repetition -/// then all track (in and outside of the repetition) must be fixed size (px or percent). Integer repetitions are just shorthand for writing out +/// then all tracks (in and outside of the repetition) must be fixed size (px or percent). Integer repetitions are just shorthand for writing out /// N tracks longhand and are not subject to the same limitations. #[derive(Clone, PartialEq, Debug, Serialize, Deserialize, Reflect)] #[reflect(PartialEq, Serialize, Deserialize)] @@ -1116,7 +1123,7 @@ impl RepeatedGridTrack { /// Create a repeating set of grid tracks with an `fr` size. /// Note that this will give the track a content-based minimum size. - /// Usually you are best off using `GridTrack::flex` instead which uses a zero minimum size + /// Usually you are best off using `GridTrack::flex` instead which uses a zero minimum size. pub fn fr>(repetition: u16, value: f32) -> T { Self { repetition: GridTrackRepetition::Count(repetition), @@ -1125,7 +1132,7 @@ impl RepeatedGridTrack { .into() } - /// Create a repeating set of grid tracks with an `minmax(0, Nfr)` size. + /// Create a repeating set of grid tracks with a `minmax(0, Nfr)` size. pub fn flex>(repetition: u16, value: f32) -> T { Self { repetition: GridTrackRepetition::Count(repetition), @@ -1245,11 +1252,18 @@ impl From for Vec { /// /// pub struct GridPlacement { - /// The grid line at which the item should start. Lines are 1-indexed. Negative indexes count backwards from the end of the grid. Zero is not a valid index. + /// The grid line at which the item should start. + /// Lines are 1-indexed. + /// Negative indexes count backwards from the end of the grid. + /// Zero is not a valid index. pub(crate) start: Option, - /// How many grid tracks the item should span. Defaults to 1. + /// How many grid tracks the item should span. + /// Defaults to 1. pub(crate) span: Option, - /// The grid line at which the item should end. Lines are 1-indexed. Negative indexes count backwards from the end of the grid. Zero is not a valid index. + /// The grid line at which the item should end. + /// Lines are 1-indexed. + /// Negative indexes count backwards from the end of the grid. + /// Zero is not a valid index. pub(crate) end: Option, } @@ -1269,7 +1283,7 @@ impl GridPlacement { /// /// # Panics /// - /// Panics if `span` is `0` + /// Panics if `span` is `0`. pub fn span(span: u16) -> Self { Self { start: None, @@ -1282,7 +1296,7 @@ impl GridPlacement { /// /// # Panics /// - /// Panics if `start` is `0` + /// Panics if `start` is `0`. pub fn start(start: i16) -> Self { Self { start: try_into_grid_index(start).expect("Invalid start value of 0."), @@ -1294,7 +1308,7 @@ impl GridPlacement { /// /// # Panics /// - /// Panics if `end` is `0` + /// Panics if `end` is `0`. pub fn end(end: i16) -> Self { Self { end: try_into_grid_index(end).expect("Invalid end value of 0."), @@ -1306,7 +1320,7 @@ impl GridPlacement { /// /// # Panics /// - /// Panics if `start` or `span` is `0` + /// Panics if `start` or `span` is `0`. pub fn start_span(start: i16, span: u16) -> Self { Self { start: try_into_grid_index(start).expect("Invalid start value of 0."), @@ -1319,7 +1333,7 @@ impl GridPlacement { /// /// # Panics /// - /// Panics if `start` or `end` is `0` + /// Panics if `start` or `end` is `0`. pub fn start_end(start: i16, end: i16) -> Self { Self { start: try_into_grid_index(start).expect("Invalid start value of 0."), @@ -1332,7 +1346,7 @@ impl GridPlacement { /// /// # Panics /// - /// Panics if `end` or `span` is `0` + /// Panics if `end` or `span` is `0`. pub fn end_span(end: i16, span: u16) -> Self { Self { start: None, @@ -1345,7 +1359,7 @@ impl GridPlacement { /// /// # Panics /// - /// Panics if `start` is `0` + /// Panics if `start` is `0`. pub fn set_start(mut self, start: i16) -> Self { self.start = try_into_grid_index(start).expect("Invalid start value of 0."); self @@ -1355,7 +1369,7 @@ impl GridPlacement { /// /// # Panics /// - /// Panics if `end` is `0` + /// Panics if `end` is `0`. pub fn set_end(mut self, end: i16) -> Self { self.end = try_into_grid_index(end).expect("Invalid end value of 0."); self @@ -1365,7 +1379,7 @@ impl GridPlacement { /// /// # Panics /// - /// Panics if `span` is `0` + /// Panics if `span` is `0`. pub fn set_span(mut self, span: u16) -> Self { self.span = try_into_grid_span(span).expect("Invalid span value of 0."); self @@ -1476,7 +1490,7 @@ impl Default for BorderColor { #[derive(Component, Copy, Clone, Default, Debug, Deserialize, Serialize, Reflect)] #[reflect(Component, Default, Deserialize, Serialize)] /// The [`Outline`] component adds an outline outside the edge of a UI node. -/// Outlines do not take up space in the layout +/// Outlines do not take up space in the layout. /// /// To add an [`Outline`] to a ui node you can spawn a `(NodeBundle, Outline)` tuple bundle: /// ``` @@ -1511,7 +1525,7 @@ impl Default for BorderColor { /// for (entity, interaction, mut maybe_outline) in node_query.iter_mut() { /// let outline_color = /// if matches!(*interaction, Interaction::Hovered) { -/// Color::WHITE +/// Color::WHITE /// } else { /// Color::NONE /// }; @@ -1528,16 +1542,16 @@ impl Default for BorderColor { pub struct Outline { /// The width of the outline. /// - /// Percentage `Val` values are resolved based on the width of the outlined [`Node`] + /// Percentage `Val` values are resolved based on the width of the outlined [`Node`]. pub width: Val, - /// The amount of space between a node's outline the edge of the node + /// The amount of space between a node's outline the edge of the node. /// - /// Percentage `Val` values are resolved based on the width of the outlined [`Node`] + /// Percentage `Val` values are resolved based on the width of the outlined [`Node`]. pub offset: Val, - /// Color of the outline + /// The color of the outline. /// /// If you are frequently toggling outlines for a UI node on and off it is recommended to set `Color::None` to hide the outline. - /// This avoids the table moves that would occcur from the repeated insertion and removal of the `Outline` component. + /// This avoids the table moves that would occur from the repeated insertion and removal of the `Outline` component. pub color: Color, } @@ -1572,14 +1586,14 @@ impl UiImage { } } - /// flip the image along its x-axis + /// Flip the image along its x-axis #[must_use] pub const fn with_flip_x(mut self) -> Self { self.flip_x = true; self } - /// flip the image along its y-axis + /// Flip the image along its y-axis #[must_use] pub const fn with_flip_y(mut self) -> Self { self.flip_y = true; @@ -1607,13 +1621,13 @@ pub struct CalculatedClip { /// /// UI nodes that have the same z-index will appear according to the order in which they /// appear in the UI hierarchy. In such a case, the last node to be added to its parent -/// will appear in front of this parent's other children. +/// will appear in front of its siblings. /// /// Internally, nodes with a global z-index share the stacking context of root UI nodes /// (nodes that have no parent). Because of this, there is no difference between using -/// [`ZIndex::Local(n)`] and [`ZIndex::Global(n)`] for root nodes. +/// `ZIndex::Local(n)` and `ZIndex::Global(n)` for root nodes. /// -/// Nodes without this component will be treated as if they had a value of [`ZIndex::Local(0)`]. +/// Nodes without this component will be treated as if they had a value of `ZIndex::Local(0)`. #[derive(Component, Copy, Clone, Debug, Reflect)] #[reflect(Component)] pub enum ZIndex {