From 79ceb9f7b6ce7d7079fd7a1e1de8b160086206d0 Mon Sep 17 00:00:00 2001
From: Eeelco <43313055+Eeelco@users.noreply.github.com>
Date: Mon, 22 Jan 2024 18:30:01 +0100
Subject: [PATCH] feat(Line): add alignment convenience functions (#856)

This adds convenience functions `left_aligned()`, `centered()` and
`right_aligned()` plus unit tests. Updated example code.
---
 examples/barchart.rs |  2 +-
 examples/layout.rs   |  3 +-
 examples/list.rs     |  2 +-
 src/text/line.rs     | 71 ++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 74 insertions(+), 4 deletions(-)

diff --git a/examples/barchart.rs b/examples/barchart.rs
index 841282f9..d4d4c1c7 100644
--- a/examples/barchart.rs
+++ b/examples/barchart.rs
@@ -185,7 +185,7 @@ fn create_groups<'a>(app: &'a App, combine_values_and_labels: bool) -> Vec<BarGr
                 })
                 .collect();
             BarGroup::default()
-                .label(Line::from(month).alignment(Alignment::Center))
+                .label(Line::from(month).centered())
                 .bars(&bars)
         })
         .collect()
diff --git a/examples/layout.rs b/examples/layout.rs
index f9338ebf..5b2d6020 100644
--- a/examples/layout.rs
+++ b/examples/layout.rs
@@ -58,8 +58,7 @@ fn ui(frame: &mut Frame) {
     // title
     frame.render_widget(
         Paragraph::new(vec![
-            Line::from("Horizontal Layout Example. Press q to quit".dark_gray())
-                .alignment(Alignment::Center),
+            Line::from("Horizontal Layout Example. Press q to quit".dark_gray()).centered(),
             Line::from("Each line has 2 constraints, plus Min(0) to fill the remaining space."),
             Line::from("E.g. the second line of the Len/Min box is [Length(2), Min(2), Min(0)]"),
             Line::from("Note: constraint labels that don't fit are truncated"),
diff --git a/examples/list.rs b/examples/list.rs
index 31ab553b..85e3e398 100644
--- a/examples/list.rs
+++ b/examples/list.rs
@@ -212,7 +212,7 @@ fn ui(f: &mut Frame, app: &mut App) {
         .items
         .iter()
         .map(|i| {
-            let mut lines = vec![Line::from(i.0.bold()).alignment(Alignment::Center)];
+            let mut lines = vec![Line::from(i.0.bold()).centered()];
             for _ in 0..i.1 {
                 lines.push(
                     "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
diff --git a/src/text/line.rs b/src/text/line.rs
index c2b7524a..1469f4d8 100644
--- a/src/text/line.rs
+++ b/src/text/line.rs
@@ -198,6 +198,8 @@ impl<'a> Line<'a> {
     /// Sets the target alignment for this line of text.
     ///
     /// Defaults to: [`None`], meaning the alignment is determined by the rendering widget.
+    /// Setting the alignment of a Line generally overrides the alignment of its
+    /// parent Text or Widget.
     ///
     /// # Examples
     ///
@@ -218,6 +220,57 @@ impl<'a> Line<'a> {
         }
     }
 
+    /// Left-aligns this line of text.
+    ///
+    /// Convenience shortcut for `Line::alignment(Alignment::Left)`.
+    /// Setting the alignment of a Line generally overrides the alignment of its
+    /// parent Text or Widget, with the default alignment being inherited from the parent.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use ratatui::prelude::*;
+    /// let line = Line::from("Hi, what's up?").left_aligned();
+    /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
+    pub fn left_aligned(self) -> Self {
+        self.alignment(Alignment::Left)
+    }
+
+    /// Center-aligns this line of text.
+    ///
+    /// Convenience shortcut for `Line::alignment(Alignment::Center)`.
+    /// Setting the alignment of a Line generally overrides the alignment of its
+    /// parent Text or Widget, with the default alignment being inherited from the parent.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use ratatui::prelude::*;
+    /// let line = Line::from("Hi, what's up?").centered();
+    /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
+    pub fn centered(self) -> Self {
+        self.alignment(Alignment::Center)
+    }
+
+    /// Right-aligns this line of text.
+    ///
+    /// Convenience shortcut for `Line::alignment(Alignment::Right)`.
+    /// Setting the alignment of a Line generally overrides the alignment of its
+    /// parent Text or Widget, with the default alignment being inherited from the parent.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # use ratatui::prelude::*;
+    /// let line = Line::from("Hi, what's up?").right_aligned();
+    /// ```
+    #[must_use = "method moves the value of self and returns the modified value"]
+    pub fn right_aligned(self) -> Self {
+        self.alignment(Alignment::Right)
+    }
+
     /// Returns the width of the underlying string.
     ///
     /// # Examples
@@ -665,4 +718,22 @@ mod tests {
             assert_buffer_eq!(buf, expected);
         }
     }
+
+    #[test]
+    fn left_aligned() {
+        let line = Line::from("Hello, world!").left_aligned();
+        assert_eq!(line.alignment, Some(Alignment::Left));
+    }
+
+    #[test]
+    fn centered() {
+        let line = Line::from("Hello, world!").centered();
+        assert_eq!(line.alignment, Some(Alignment::Center));
+    }
+
+    #[test]
+    fn right_aligned() {
+        let line = Line::from("Hello, world!").right_aligned();
+        assert_eq!(line.alignment, Some(Alignment::Right));
+    }
 }