diff --git a/src/layout.rs b/src/layout.rs index 51a8605e..cfa1e615 100644 --- a/src/layout.rs +++ b/src/layout.rs @@ -50,6 +50,27 @@ thread_local! { /// calls with the same parameters are faster. The cache is a simple HashMap, and grows /// indefinitely. (See for more information) /// +/// # Constructors +/// +/// There are four ways to create a new layout: +/// +/// - [`Layout::default`]: create a new layout with default values +/// - [`Layout::new`]: create a new layout with a given direction and constraints +/// - [`Layout::vertical`]: create a new vertical layout with the given constraints +/// - [`Layout::horizontal`]: create a new horizontal layout with the given constraints +/// +/// # Setters +/// +/// There are several setters to modify the layout: +/// +/// - [`Layout::direction`]: set the direction of the layout +/// - [`Layout::constraints`]: set the constraints of the layout +/// - [`Layout::margin`]: set the margin of the layout +/// - [`Layout::horizontal_margin`]: set the horizontal margin of the layout +/// - [`Layout::vertical_margin`]: set the vertical margin of the layout +/// - [`Layout::segment_size`]: set the way the space is distributed when the constraints are +/// satisfied +/// /// # Example /// /// ```rust @@ -284,6 +305,44 @@ impl Layout { } } + /// Creates a new vertical layout with default values. + /// + /// The `constraints` parameter accepts any type that implements `IntoIterator>`. This includes arrays, slices, vectors, iterators, etc. + /// + /// # Examples + /// + /// ```rust + /// # use ratatui::prelude::*; + /// let layout = Layout::vertical([Constraint::Length(5), Constraint::Min(0)]); + /// ``` + pub fn vertical(constraints: I) -> Layout + where + I: IntoIterator, + I::Item: AsRef, + { + Layout::new(Direction::Vertical, constraints) + } + + /// Creates a new horizontal layout with default values. + /// + /// The `constraints` parameter accepts any type that implements `IntoIterator>`. This includes arrays, slices, vectors, iterators, etc. + /// + /// # Examples + /// + /// ```rust + /// # use ratatui::prelude::*; + /// let layout = Layout::horizontal([Constraint::Length(5), Constraint::Min(0)]); + /// ``` + pub fn horizontal(constraints: I) -> Layout + where + I: IntoIterator, + I::Item: AsRef, + { + Layout::new(Direction::Horizontal, constraints) + } + /// Initialize an empty cache with a custom size. The cache is keyed on the layout and area, so /// that subsequent calls with the same parameters are faster. The cache is a LruCache, and /// grows until `cache_size` is reached. @@ -878,6 +937,32 @@ mod tests { assert_eq!(layout.constraints, [Constraint::Min(0)]); } + #[test] + fn layout_vertical() { + assert_eq!( + Layout::vertical([Constraint::Min(0)]), + Layout { + direction: Direction::Vertical, + margin: Margin::new(0, 0), + constraints: vec![Constraint::Min(0)], + segment_size: LastTakesRemainder, + } + ); + } + + #[test] + fn layout_horizontal() { + assert_eq!( + Layout::horizontal([Constraint::Min(0)]), + Layout { + direction: Direction::Horizontal, + margin: Margin::new(0, 0), + constraints: vec![Constraint::Min(0)], + segment_size: LastTakesRemainder, + } + ); + } + /// The purpose of this test is to ensure that layout can be constructed with any type that /// implements IntoIterator>. #[test]