From eacf0f9e41430fa4656fb64de19bf242a5e0c299 Mon Sep 17 00:00:00 2001
From: Greg Price <greg@zulip.com>
Date: Tue, 20 Feb 2024 10:59:12 -0800
Subject: [PATCH] Explain when and why to use CrossAxisAlignment.baseline
(#143632)
Improves the docs around horizontal alignment of text, due to several issues expressing confusion about this topic.
---
packages/flutter/lib/src/rendering/flex.dart | 25 ++++++++++++++++++--
packages/flutter/lib/src/widgets/basic.dart | 15 ++++++++++++
2 files changed, 38 insertions(+), 2 deletions(-)
diff --git a/packages/flutter/lib/src/rendering/flex.dart b/packages/flutter/lib/src/rendering/flex.dart
index 9c6887ee3899..db5263461046 100644
--- a/packages/flutter/lib/src/rendering/flex.dart
+++ b/packages/flutter/lib/src/rendering/flex.dart
@@ -142,6 +142,8 @@ enum MainAxisAlignment {
/// See also:
///
/// * [Column], [Row], and [Flex], the flex widgets.
+/// * [Flex.crossAxisAlignment], the property on flex widgets that
+/// has this type.
/// * [RenderFlex], the flex render object.
enum CrossAxisAlignment {
/// Place the children with their start edge aligned with the start side of
@@ -185,9 +187,24 @@ enum CrossAxisAlignment {
/// Place the children along the cross axis such that their baselines match.
///
+ /// Consider using this value for any horizontal main axis (as with [Row])
+ /// where the children primarily contain text. If the different children
+ /// have text with different font metrics (for example because they differ
+ /// in [TextStyle.fontSize] or other [TextStyle] properties, or because
+ /// they use different fonts due to being written in different scripts),
+ /// then this typically produces better visual alignment than the other
+ /// [CrossAxisAlignment] values, which use no information about
+ /// where the text sits vertically within its bounding box.
+ ///
+ /// The baseline of a widget is typically the typographic baseline of the
+ /// first text in the first [Text] or [RichText] widget it encloses, if any.
+ /// The typographic baseline is a horizontal line used for aligning text,
+ /// which is specified by each font; for alphabetic scripts, it ordinarily
+ /// runs along the bottom of letters excluding any descenders.
+ ///
/// Because baselines are always horizontal, this alignment is intended for
- /// horizontal main axes. If the main axis is vertical, then this value is
- /// treated like [start].
+ /// horizontal main axes (as with [Row]). If the main axis is vertical
+ /// (as with [Column]), then this value is treated like [start].
///
/// For horizontal main axes, if the minimum height constraint passed to the
/// flex layout exceeds the intrinsic height of the cross axis, children will
@@ -195,6 +212,10 @@ enum CrossAxisAlignment {
/// alignment. In other words, the extra space will be below all the children.
///
/// Children who report no baseline will be top-aligned.
+ ///
+ /// See also:
+ ///
+ /// * [RenderBox.getDistanceToBaseline], which defines the baseline of a box.
baseline,
}
diff --git a/packages/flutter/lib/src/widgets/basic.dart b/packages/flutter/lib/src/widgets/basic.dart
index 51f186503e80..6b35233027e4 100644
--- a/packages/flutter/lib/src/widgets/basic.dart
+++ b/packages/flutter/lib/src/widgets/basic.dart
@@ -4629,6 +4629,13 @@ class Flex extends MultiChildRenderObjectWidget {
///
/// For example, [CrossAxisAlignment.center], the default, centers the
/// children in the cross axis (e.g., horizontally for a [Column]).
+ ///
+ /// When the cross axis is vertical (as for a [Row]) and the children
+ /// contain text, consider using [CrossAxisAlignment.baseline] instead.
+ /// This typically produces better visual results if the different children
+ /// have text with different font metrics, for example because they differ in
+ /// [TextStyle.fontSize] or other [TextStyle] properties, or because
+ /// they use different fonts due to being written in different scripts.
final CrossAxisAlignment crossAxisAlignment;
/// Determines the order to lay children out horizontally and how to interpret
@@ -4778,6 +4785,14 @@ class Flex extends MultiChildRenderObjectWidget {
/// If you only have one child, then consider using [Align] or [Center] to
/// position the child.
///
+/// By default, [crossAxisAlignment] is [CrossAxisAlignment.center], which
+/// centers the children in the vertical axis. If several of the children
+/// contain text, this is likely to make them visually misaligned if
+/// they have different font metrics (for example because they differ in
+/// [TextStyle.fontSize] or other [TextStyle] properties, or because
+/// they use different fonts due to being written in different scripts).
+/// Consider using [CrossAxisAlignment.baseline] instead.
+///
/// {@tool snippet}
///
/// This example divides the available space into three (horizontally), and