forestia/bevy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Tidy up UI node docs (#10189)

Browse Source 
# Objective

While reviewing #10187 I noticed some other mistakes in the UI node
docs.

## Solution

I did a quick proofreading pass and fixed a few things. And of course,
the typo from that other PR.

## Notes

I occasionally insert a period to make a section of doc self-consistent
but didn't go one way or the other on all periods in the file.

---------

Co-authored-by: Noah <noahshomette@gmail.com>
This commit is contained in:
Rob Parrett 2023-10-21 10:38:15 -07:00 committed by GitHub
parent 6f2a5cb862
commit 38e0a8010e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 98 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

182
crates/bevy_ui/src/ui_node.rs
View File

@ -14,29 +14,34 @@ use thiserror::Error;
#[derive(Component, Debug, Copy, Clone, Reflect)] #[derive(Component, Debug, Copy, Clone, Reflect)]
#[reflect(Component, Default)] #[reflect(Component, Default)]
pub struct Node { pub struct Node {
/// The size of the node as width and height in logical pixels /// The size of the node as width and height in logical pixels.
/// automatically calculated by [`super::layout::ui_layout_system`] ///
/// Automatically calculated by [`super::layout::ui_layout_system`].
pub(crate) calculated_size: Vec2, pub(crate) calculated_size: Vec2,
/// The width of this node's outline /// The width of this node's outline.
/// If this value is `Auto`, negative or `0.` then no outline will be rendered /// If this value is `Auto`, negative or `0.` then no outline will be rendered.
/// automatically calculated by [`super::layout::resolve_outlines_system`] ///
/// Automatically calculated by [`super::layout::resolve_outlines_system`].
pub(crate) outline_width: f32, 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, pub(crate) outline_offset: f32,
/// The unrounded size of the node as width and height in logical pixels /// The unrounded size of the node as width and height in logical pixels.
/// automatically calculated by [`super::layout::ui_layout_system`] ///
/// Automatically calculated by [`super::layout::ui_layout_system`].
pub(crate) unrounded_size: Vec2, pub(crate) unrounded_size: Vec2,
} }
impl Node { impl Node {
/// The calculated node size as width and height in logical pixels /// The calculated node size as width and height in logical pixels.
/// automatically calculated by [`super::layout::ui_layout_system`] ///
/// Automatically calculated by [`super::layout::ui_layout_system`].
pub const fn size(&self) -> Vec2 { pub const fn size(&self) -> Vec2 {
self.calculated_size self.calculated_size
} }
/// The calculated node size as width and height in logical pixels before rounding /// The calculated node size as width and height in logical pixels before rounding.
/// automatically calculated by [`super::layout::ui_layout_system`] ///
/// Automatically calculated by [`super::layout::ui_layout_system`].
pub const fn unrounded_size(&self) -> Vec2 { pub const fn unrounded_size(&self) -> Vec2 {
self.unrounded_size self.unrounded_size
} }
@ -102,7 +107,8 @@ impl Default for Node {
/// Describes the style of a UI container node /// Describes the style of a UI container node
/// ///
/// Node's can be laid out using either Flexbox or CSS Grid Layout.<br /> /// 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. /// See below for general learning resources and for documentation on the individual style properties.
/// ///
/// ### Flexbox /// ### Flexbox
@ -128,7 +134,7 @@ pub struct Style {
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/display> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/display>
pub display: Display, 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::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. /// - [`PositionType::Absolute`]: Layout this node on top and independently of other nodes.
/// ///
@ -140,9 +146,10 @@ pub struct Style {
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/overflow> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/overflow>
pub overflow: Overflow, 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.
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/direction> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/direction>
pub direction: Direction, pub direction: Direction,
@ -184,12 +191,12 @@ pub struct Style {
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/height> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/height>
pub height: Val, 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`.
/// ///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/min-width> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/min-width>
pub min_width: Val, 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`.
/// ///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/min-height> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/min-height>
pub min_height: Val, pub min_height: Val,
@ -226,7 +233,7 @@ pub struct Style {
pub justify_items: JustifyItems, pub justify_items: JustifyItems,
/// - For Flexbox items, controls cross-axis alignment of the item. /// - 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. /// 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, pub align_self: AlignSelf,
/// - For Flexbox items, this property has no effect. See `justify_content` for main-axis alignment of flex items. /// - 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. /// If set to `Auto`, alignment is inherited from the value of [`JustifyItems`] set on the parent node.
/// ///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/justify-self>
pub justify_self: JustifySelf, 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. /// - 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() /// ..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.
/// ///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/margin> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/margin>
pub margin: UiRect, pub margin: UiRect,
@ -292,7 +299,7 @@ pub struct Style {
/// ..Default::default() /// ..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.
/// ///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/padding> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/padding>
pub padding: UiRect, pub padding: UiRect,
@ -306,12 +313,12 @@ pub struct Style {
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/border-width> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/border-width>
pub border: UiRect, 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.
/// ///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction>
pub flex_direction: FlexDirection, 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.
/// ///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap>
pub flex_wrap: FlexWrap, 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. /// 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`.
/// ///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/flex-basis> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/flex-basis>
pub flex_basis: Val, 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. /// Note: Values of `Val::Auto` are not valid and are treated as zero.
/// ///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/row-gap> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/row-gap>
pub row_gap: Val, 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. /// Note: Values of `Val::Auto` are not valid and are treated as zero.
/// ///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/column-gap> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/column-gap>
pub column_gap: Val, 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. /// 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 affect Grid layouts /// Only affects Grid layouts.
/// ///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-flow> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-flow>
pub grid_auto_flow: GridAutoFlow, 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 /// 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`. /// of the columns explicitly created using `grid_template_columns`.
/// ///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-columns>
pub grid_auto_columns: Vec<GridTrack>, pub grid_auto_columns: Vec<GridTrack>,
/// The row in which a grid item starts and how many rows it spans. /// 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)] #[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)]
#[reflect(PartialEq, Serialize, Deserialize)] #[reflect(PartialEq, Serialize, Deserialize)]
pub enum AlignItems { 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, Default,
/// Items are packed towards the start of the axis. /// Items are packed towards the start of the axis.
Start, Start,
@ -474,7 +481,7 @@ impl Default for AlignItems {
#[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)] #[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)]
#[reflect(PartialEq, Serialize, Deserialize)] #[reflect(PartialEq, Serialize, Deserialize)]
pub enum JustifyItems { 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, Default,
/// Items are packed towards the start of the axis. /// Items are packed towards the start of the axis.
Start, Start,
@ -568,7 +575,7 @@ impl Default for JustifySelf {
#[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)] #[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)]
#[reflect(PartialEq, Serialize, Deserialize)] #[reflect(PartialEq, Serialize, Deserialize)]
pub enum AlignContent { 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, Default,
/// Each line moves towards the start of the cross axis. /// Each line moves towards the start of the cross axis.
Start, Start,
@ -582,13 +589,13 @@ pub enum AlignContent {
Center, Center,
/// Each line will stretch to fill the remaining space. /// Each line will stretch to fill the remaining space.
Stretch, Stretch,
/// 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,
/// inbetween the lines. /// between the lines.
SpaceBetween, 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. /// The gaps are distributed evenly.
SpaceEvenly, 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. /// around the lines.
SpaceAround, SpaceAround,
} }
@ -607,7 +614,7 @@ impl Default for AlignContent {
#[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)] #[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)]
#[reflect(PartialEq, Serialize, Deserialize)] #[reflect(PartialEq, Serialize, Deserialize)]
pub enum JustifyContent { 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, Default,
/// Items are packed toward the start of the axis. /// Items are packed toward the start of the axis.
Start, 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)] #[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)]
#[reflect(PartialEq, Serialize, Deserialize)] #[reflect(PartialEq, Serialize, Deserialize)]
pub enum Direction { 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. /// Part of the [`Style`] component.
#[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)] #[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)]
@ -803,9 +810,7 @@ impl Default for OverflowAxis {
pub enum PositionType { pub enum PositionType {
/// Relative to all other nodes with the [`PositionType::Relative`] value. /// Relative to all other nodes with the [`PositionType::Relative`] value.
Relative, Relative,
/// Independent of all other nodes. /// Independent of all other nodes, but relative to its parent node.
///
/// As usual, the `Style.position` field of this node is specified relative to its parent node.
Absolute, 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`].
/// ///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-flow> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-flow>
#[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)] #[derive(Copy, Clone, PartialEq, Eq, Debug, Serialize, Deserialize, Reflect)]
#[reflect(PartialEq, Serialize, Deserialize)] #[reflect(PartialEq, Serialize, Deserialize)]
pub enum GridAutoFlow { 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, Row,
/// Items are placed by filling each column in turn, adding new columns as necessary. /// Items are placed by filling each column in turn, adding new columns as necessary.
Column, Column,
@ -904,7 +910,8 @@ pub enum MaxTrackSizingFunction {
/// Track maximum size should be automatically sized /// Track maximum size should be automatically sized
Auto, Auto,
/// The dimension as a fraction of the total available grid space (`fr` units in CSS) /// 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: <https://www.w3.org/TR/css3-grid-layout/#fr-unit> /// Spec: <https://www.w3.org/TR/css3-grid-layout/#fr-unit>
Fraction(f32), Fraction(f32),
} }
@ -944,7 +951,7 @@ impl GridTrack {
/// Create a grid track with an `fr` size. /// Create a grid track with an `fr` size.
/// Note that this will give the track a content-based minimum 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<T: From<Self>>(value: f32) -> T { pub fn fr<T: From<Self>>(value: f32) -> T {
Self { Self {
min_sizing_function: MinTrackSizingFunction::Auto, min_sizing_function: MinTrackSizingFunction::Auto,
@ -953,7 +960,7 @@ impl GridTrack {
.into() .into()
} }
/// Create a grid track with an `minmax(0, Nfr)` size. /// Create a grid track with a `minmax(0, Nfr)` size.
pub fn flex<T: From<Self>>(value: f32) -> T { pub fn flex<T: From<Self>>(value: f32) -> T {
Self { Self {
min_sizing_function: MinTrackSizingFunction::Px(0.0), min_sizing_function: MinTrackSizingFunction::Px(0.0),
@ -962,7 +969,7 @@ impl GridTrack {
.into() .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: From<Self>>() -> T { pub fn auto<T: From<Self>>() -> T {
Self { Self {
min_sizing_function: MinTrackSizingFunction::Auto, min_sizing_function: MinTrackSizingFunction::Auto,
@ -971,7 +978,7 @@ impl GridTrack {
.into() .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: From<Self>>() -> T { pub fn min_content<T: From<Self>>() -> T {
Self { Self {
min_sizing_function: MinTrackSizingFunction::MinContent, min_sizing_function: MinTrackSizingFunction::MinContent,
@ -980,7 +987,7 @@ impl GridTrack {
.into() .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: From<Self>>() -> T { pub fn max_content<T: From<Self>>() -> T {
Self { Self {
min_sizing_function: MinTrackSizingFunction::MaxContent, min_sizing_function: MinTrackSizingFunction::MaxContent,
@ -1070,14 +1077,14 @@ impl From<usize> for GridTrackRepetition {
/// ///
/// The repetition parameter can either be: /// The repetition parameter can either be:
/// - The integer `1`, in which case the track is non-repeated. /// - The integer `1`, in which case the track is non-repeated.
/// - a `u16` count to repeat the track N times /// - a `u16` count to repeat the track N times.
/// - A `GridTrackRepetition::AutoFit` or `GridTrackRepetition::AutoFill` /// - 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`] /// 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)`. /// 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 /// 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. /// N tracks longhand and are not subject to the same limitations.
#[derive(Clone, PartialEq, Debug, Serialize, Deserialize, Reflect)] #[derive(Clone, PartialEq, Debug, Serialize, Deserialize, Reflect)]
#[reflect(PartialEq, Serialize, Deserialize)] #[reflect(PartialEq, Serialize, Deserialize)]
@ -1116,7 +1123,7 @@ impl RepeatedGridTrack {
/// Create a repeating set of grid tracks with an `fr` size. /// Create a repeating set of grid tracks with an `fr` size.
/// Note that this will give the track a content-based minimum 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<T: From<Self>>(repetition: u16, value: f32) -> T { pub fn fr<T: From<Self>>(repetition: u16, value: f32) -> T {
Self { Self {
repetition: GridTrackRepetition::Count(repetition), repetition: GridTrackRepetition::Count(repetition),
@ -1125,7 +1132,7 @@ impl RepeatedGridTrack {
.into() .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<T: From<Self>>(repetition: u16, value: f32) -> T { pub fn flex<T: From<Self>>(repetition: u16, value: f32) -> T {
Self { Self {
repetition: GridTrackRepetition::Count(repetition), repetition: GridTrackRepetition::Count(repetition),
@ -1245,11 +1252,18 @@ impl From<RepeatedGridTrack> for Vec<RepeatedGridTrack> {
/// ///
/// <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout/Line-based_Placement_with_CSS_Grid> /// <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout/Line-based_Placement_with_CSS_Grid>
pub struct GridPlacement { 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<NonZeroI16>, pub(crate) start: Option<NonZeroI16>,
/// 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<NonZeroU16>, pub(crate) span: Option<NonZeroU16>,
/// 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<NonZeroI16>, pub(crate) end: Option<NonZeroI16>,
} }
@ -1269,7 +1283,7 @@ impl GridPlacement {
/// ///
/// # Panics /// # Panics
/// ///
/// Panics if `span` is `0` /// Panics if `span` is `0`.
pub fn span(span: u16) -> Self { pub fn span(span: u16) -> Self {
Self { Self {
start: None, start: None,
@ -1282,7 +1296,7 @@ impl GridPlacement {
/// ///
/// # Panics /// # Panics
/// ///
/// Panics if `start` is `0` /// Panics if `start` is `0`.
pub fn start(start: i16) -> Self { pub fn start(start: i16) -> Self {
Self { Self {
start: try_into_grid_index(start).expect("Invalid start value of 0."), start: try_into_grid_index(start).expect("Invalid start value of 0."),
@ -1294,7 +1308,7 @@ impl GridPlacement {
/// ///
/// # Panics /// # Panics
/// ///
/// Panics if `end` is `0` /// Panics if `end` is `0`.
pub fn end(end: i16) -> Self { pub fn end(end: i16) -> Self {
Self { Self {
end: try_into_grid_index(end).expect("Invalid end value of 0."), end: try_into_grid_index(end).expect("Invalid end value of 0."),
@ -1306,7 +1320,7 @@ impl GridPlacement {
/// ///
/// # Panics /// # Panics
/// ///
/// Panics if `start` or `span` is `0` /// Panics if `start` or `span` is `0`.
pub fn start_span(start: i16, span: u16) -> Self { pub fn start_span(start: i16, span: u16) -> Self {
Self { Self {
start: try_into_grid_index(start).expect("Invalid start value of 0."), start: try_into_grid_index(start).expect("Invalid start value of 0."),
@ -1319,7 +1333,7 @@ impl GridPlacement {
/// ///
/// # Panics /// # Panics
/// ///
/// Panics if `start` or `end` is `0` /// Panics if `start` or `end` is `0`.
pub fn start_end(start: i16, end: i16) -> Self { pub fn start_end(start: i16, end: i16) -> Self {
Self { Self {
start: try_into_grid_index(start).expect("Invalid start value of 0."), start: try_into_grid_index(start).expect("Invalid start value of 0."),
@ -1332,7 +1346,7 @@ impl GridPlacement {
/// ///
/// # Panics /// # Panics
/// ///
/// Panics if `end` or `span` is `0` /// Panics if `end` or `span` is `0`.
pub fn end_span(end: i16, span: u16) -> Self { pub fn end_span(end: i16, span: u16) -> Self {
Self { Self {
start: None, start: None,
@ -1345,7 +1359,7 @@ impl GridPlacement {
/// ///
/// # Panics /// # Panics
/// ///
/// Panics if `start` is `0` /// Panics if `start` is `0`.
pub fn set_start(mut self, start: i16) -> Self { pub fn set_start(mut self, start: i16) -> Self {
self.start = try_into_grid_index(start).expect("Invalid start value of 0."); self.start = try_into_grid_index(start).expect("Invalid start value of 0.");
self self
@ -1355,7 +1369,7 @@ impl GridPlacement {
/// ///
/// # Panics /// # Panics
/// ///
/// Panics if `end` is `0` /// Panics if `end` is `0`.
pub fn set_end(mut self, end: i16) -> Self { pub fn set_end(mut self, end: i16) -> Self {
self.end = try_into_grid_index(end).expect("Invalid end value of 0."); self.end = try_into_grid_index(end).expect("Invalid end value of 0.");
self self
@ -1365,7 +1379,7 @@ impl GridPlacement {
/// ///
/// # Panics /// # Panics
/// ///
/// Panics if `span` is `0` /// Panics if `span` is `0`.
pub fn set_span(mut self, span: u16) -> Self { pub fn set_span(mut self, span: u16) -> Self {
self.span = try_into_grid_span(span).expect("Invalid span value of 0."); self.span = try_into_grid_span(span).expect("Invalid span value of 0.");
self self
@ -1476,7 +1490,7 @@ impl Default for BorderColor {
#[derive(Component, Copy, Clone, Default, Debug, Deserialize, Serialize, Reflect)] #[derive(Component, Copy, Clone, Default, Debug, Deserialize, Serialize, Reflect)]
#[reflect(Component, Default, Deserialize, Serialize)] #[reflect(Component, Default, Deserialize, Serialize)]
/// The [`Outline`] component adds an outline outside the edge of a UI node. /// 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: /// 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() { /// for (entity, interaction, mut maybe_outline) in node_query.iter_mut() {
/// let outline_color = /// let outline_color =
/// if matches!(*interaction, Interaction::Hovered) { /// if matches!(*interaction, Interaction::Hovered) {
/// Color::WHITE /// Color::WHITE
/// } else { /// } else {
/// Color::NONE /// Color::NONE
/// }; /// };
@ -1528,16 +1542,16 @@ impl Default for BorderColor {
pub struct Outline { pub struct Outline {
/// The width of the 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, 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, 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. /// 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, 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] #[must_use]
pub const fn with_flip_x(mut self) -> Self { pub const fn with_flip_x(mut self) -> Self {
self.flip_x = true; self.flip_x = true;
self self
} }
/// flip the image along its y-axis /// Flip the image along its y-axis
#[must_use] #[must_use]
pub const fn with_flip_y(mut self) -> Self { pub const fn with_flip_y(mut self) -> Self {
self.flip_y = true; 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 /// 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 /// 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 /// 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 /// (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)] #[derive(Component, Copy, Clone, Debug, Reflect)]
#[reflect(Component)] #[reflect(Component)]
pub enum ZIndex { pub enum ZIndex {