Skip to content

F
Front-End
Unverified Commit 9c1783e9 authored by Gary Qian's avatar Gary Qian Committed by GitHub
Browse files
Options

Update TextStyle and StrutStyle height docs (#33281)

parent aae50f54
Show whitespace changes
Inline Side-by-side
Showing with 152 additions and 72 deletions
packages/flutter/lib/src/painting/strut_style.dart
View file @ 9c1783e9
......@@ -8,19 +8,21 @@ import 'basic_types.dart';
import 'text_style.dart';
/// Defines the strut, which sets the minimum height a line can be
/// relative to the baseline. Strut applies to all lines in the paragraph.
///
/// Strut is a feature that allows minimum line heights to be set. The effect is as
/// if a zero width space was included at the beginning of each line in the
/// paragraph. This imaginary space is 'shaped' according the properties defined
/// in this class. Flutter's strut is based on [typesetting strut](https://en.wikipedia.org/wiki/Strut_(typesetting))
/// relative to the baseline.
///
/// Strut applies to all lines in the paragraph. Strut is a feature that
/// allows minimum line heights to be set. The effect is as if a zero
/// width space was included at the beginning of each line in the
/// paragraph. This imaginary space is 'shaped' according the properties
/// defined in this class. Flutter's strut is based on
/// [typesetting strut](https://en.wikipedia.org/wiki/Strut_(typesetting))
/// and CSS's [line-height](https://www.w3.org/TR/CSS2/visudet.html#line-height).
///
/// No lines may be shorter than the strut. The ascent and descent of the strut
/// are calculated, and any laid out text that has a shorter ascent or descent than
/// the strut's ascent or descent will take the ascent and descent of the strut.
/// Text with ascents or descents larger than the strut's ascent or descent will lay
/// out as normal and extend past the strut.
/// No lines may be shorter than the strut. The ascent and descent of the
/// strut are calculated, and any laid out text that has a shorter ascent or
/// descent than the strut's ascent or descent will take the ascent and
/// descent of the strut. Text with ascents or descents larger than the
/// strut's ascent or descent will layout as normal and extend past the strut.
///
/// Strut is defined independently from any text content or [TextStyle]s.
///
......@@ -33,16 +35,26 @@ import 'text_style.dart';
///
/// The sum of these four values is the total height of the line.
///
/// The `ascent + descent` is equivalent to the [fontSize]. Ascent is the font's
/// spacing above the baseline without leading and descent is the spacing below the
/// baseline without leading. Leading is split evenly between the top and bottom.
/// The values for `ascent` and `descent` are provided by the font named by
/// [fontFamily]. If no [fontFamily] or [fontFamilyFallback] is provided, then the
/// platform's default family will be used.
/// Ascent is the font's spacing above the baseline without leading and
/// descent is the spacing below the baseline without leading. Leading is
/// split evenly betweenthe top and bottom. The values for `ascent` and
/// `descent` are provided by the font named by [fontFamily]. If no
/// [fontFamily] or [fontFamilyFallback] is provided, then the platform's
/// default family will be used.
///
/// When [height] is omitted or null, then the font defined ascent and descent
/// will be used. The font's combined ascent and descent may be taller or
/// shorter than the [fontSize]. When [height] is provided, the line's EM-square
/// ascent and descent (which sums to [fontSize]) will be scaled by [height] to
/// achieve a final line height of `fontSize * height + fontSize * leading`
/// logical pixels. The proportion of ascent:descent with [height] specified
/// is the same as the font metrics defined ascent:descent ratio.
///
/// ![Text height diagram](https://flutter.github.io/assets-for-api-docs/assets/painting/text_height_diagram.png)
///
/// Each line's spacing above the baseline will be at least as tall as the half
/// leading plus ascent. Each line's spacing below the baseline will be at least as
/// tall as the half leading plus descent.
/// Each line's spacing above the baseline will be at least as tall as the
/// half leading plus ascent. Each line's spacing below the baseline will
/// be at least as tall as the half leading plus descent.
///
/// See also:
///
......@@ -65,47 +77,55 @@ import 'text_style.dart';
/// (e.g., Roboto). No glyphs from the font will be drawn and the font will
/// be used purely for metrics.
///
/// * [fontFamilyFallback]: an ordered list of font family names that will be searched for when
/// the font in [fontFamily] cannot be found. When all specified font families have been
/// exhausted an no match was found, the default platform font will be used.
/// * [fontFamilyFallback]: an ordered list of font family names that will
/// be searched for when the font in [fontFamily] cannot be found. When
/// all specified font families have been exhausted an no match was found,
/// the default platform font will be used.
///
/// * [fontSize]: the size of the ascent plus descent in logical pixels. This
/// is also used as the basis of the custom leading calculation. This value
/// cannot be negative.
/// Default is 14 logical pixels.
///
/// * [height]: the multiple of [fontSize] to multiply the ascent and descent by.
/// The [height] will impact the spacing above and below the baseline differently
/// depending on the ratios between the font's ascent and descent. This property is
/// separate from the leading multiplier, which is controlled through [leading].
/// Default is 1.0.
///
/// * [leading]: the custom leading to apply to the strut as a multiple of [fontSize].
/// Leading is additional spacing between lines. Half of the leading is added
/// to the top and the other half to the bottom of the line height. This differs
/// from [height] since the spacing is equally distributed above and below the
/// baseline.
/// Default is `null`, which will use the font-specified leading.
///
/// * [fontWeight]: the typeface thickness to use when calculating the strut (e.g., bold).
/// * [height]: the multiple of [fontSize] the line's height should be.
/// The line's height will take the font's ascent and descent values if
/// [height] is omitted or null. If provided, the EM-square ascent and
/// descent (which sum to [fontSize]) is scaled by [height].
/// The [height] will impact the spacing above and below the baseline
/// differently depending on the ratios between the font's ascent and
/// descent. This property is separate from the leading multiplier, which
/// is controlled through [leading].
/// Default is null.
///
/// * [leading]: the custom leading to apply to the strut as a multiple of
/// [fontSize]. Leading is additional spacing between lines. Half of the
/// leading is added to the top and the other half to the bottom of the
/// line height. This differs from [height] since the spacing is equally
/// distributed above and below the baseline.
/// Default is null, which will use the font-specified leading.
///
/// * [fontWeight]: the typeface thickness to use when calculating the strut
/// (e.g., bold).
/// Default is [FontWeight.w400].
///
/// * [fontStyle]: the typeface variant to use when calculating the strut (e.g., italic).
/// * [fontStyle]: the typeface variant to use when calculating the strut
/// (e.g., italic).
/// Default is [FontStyle.normal].
///
/// * [forceStrutHeight]: when true, all lines will be laid out with the height of the
/// strut. All line and run-specific metrics will be ignored/overridden and only strut
/// metrics will be used instead. This property guarantees uniform line spacing, however
/// text in adjacent lines may overlap. This property should be enabled with caution as
/// it bypasses a large portion of the vertical layout system.
/// * [forceStrutHeight]: when true, all lines will be laid out with the
/// height of the strut. All line and run-specific metrics will be
/// ignored/overridden and only strut metrics will be used instead.
/// This property guarantees uniform line spacing, however text in
/// adjacent lines may overlap. This property should be enabled with
/// caution as it bypasses a large portion of the vertical layout system.
/// The default value is false.
///
/// ### Examples
///
/// {@tool sample}
/// In this simple case, the text will be rendered at font size 10, however, the vertical
/// height of each line will be the strut height (Roboto in font size 30 * 1.5) as the text
/// itself is shorter than the strut.
/// In this simple case, the text will be rendered at font size 10, however,
/// the vertical height of each line will be the strut height (Roboto in
/// font size 30 * 1.5) as the text itself is shorter than the strut.
///
/// ```dart
/// const Text(
......@@ -271,7 +291,8 @@ class StrutStyle extends Diagnosticable {
/// package. It is combined with the `fontFamily` argument to set the
/// [fontFamily] property.
///
/// If provided, fontSize must be positive and non-zero, leading must be zero or positive.
/// If provided, fontSize must be positive and non-zero, leading must be
/// zero or positive.
const StrutStyle({
String fontFamily,
List<String> fontFamilyFallback,
......@@ -296,16 +317,19 @@ class StrutStyle extends Diagnosticable {
/// The [textStyle] parameter must not be null.
///
/// The named parameters override the [textStyle]'s argument's properties.
/// Since TextStyle does not contain [leading] or [forceStrutHeight], these values
/// will take on default values (null and false) unless otherwise specified.
/// Since TextStyle does not contain [leading] or [forceStrutHeight], these
/// values will take on default values (null and false) unless otherwise
/// specified.
///
/// If provided, fontSize must be positive and non-zero, leading must be zero or positive.
/// If provided, fontSize must be positive and non-zero, leading must be
/// zero or positive.
///
/// When [textStyle] has a package and a new [package] is also specified, the entire
/// font family fallback list should be redefined since the [textStyle]'s package data
/// is inherited by being prepended onto the font family names. If
/// [fontFamilyFallback] is meant to be empty, pass an empty list instead of null.
/// This prevents the previous package name from being prepended twice.
/// When [textStyle] has a package and a new [package] is also specified,
/// the entire font family fallback list should be redefined since the
/// [textStyle]'s package data is inherited by being prepended onto the
/// font family names. If [fontFamilyFallback] is meant to be empty, pass
/// an empty list instead of null. This prevents the previous package name
/// from being prepended twice.
StrutStyle.fromTextStyle(
TextStyle textStyle, {
String fontFamily,
......@@ -329,8 +353,8 @@ class StrutStyle extends Diagnosticable {
fontWeight = fontWeight ?? textStyle.fontWeight,
fontStyle = fontStyle ?? textStyle.fontStyle,
debugLabel = debugLabel ?? textStyle.debugLabel,
_package = package; // the textStyle._package data is embedded in the fontFamily names,
// so we no longer need it.
_package = package; // the textStyle._package data is embedded in the
// fontFamily names, so we no longer need it.
/// A [StrutStyle] that will have no impact on the text layout.
///
......@@ -394,15 +418,32 @@ class StrutStyle extends Diagnosticable {
/// The default fontSize is 14 logical pixels.
final double fontSize;
/// The multiple of [fontSize] to multiply the ascent and descent by where `ascent + descent = fontSize`.
/// The multiple of [fontSize] to multiply the ascent and descent by where
/// `ascent + descent = fontSize`.
///
/// Ascent is the spacing above the baseline and descent is the spacing below the baseline.
/// Ascent is the spacing above the baseline and descent is the spacing below
/// the baseline.
///
/// When [height] is omitted or null, then the font defined ascent and descent
/// will be used. The font's combined ascent and descent may be taller or
/// shorter than the [fontSize]. When [height] is provided, the line's EM-square
/// ascent and descent (which sums to [fontSize]) will be scaled by [height] to
/// achieve a final line height of `fontSize * height + fontSize * leading`
/// logical pixels. The following diagram illustrates the differences between
/// the font metrics defined height and the EM-square height:
///
/// ![Text height diagram](https://flutter.github.io/assets-for-api-docs/assets/painting/text_height_diagram.png)
///
/// The [height] will impact the spacing above and below the baseline differently
/// depending on the ratios between the font's ascent and descent. This property is
/// separate from the leading multiplier, which is controlled through [leading].
///
/// The default height is 1.0.
/// The ratio of ascent:descent with [height] specified is the same as the
/// font metrics defined ascent:descent ratio when [height] is null or omitted.
///
/// See [TextStyle.height], which works in a similar manner.
///
/// The default height is null.
final double height;
/// The typeface thickness to use when calculating the strut (e.g., bold).
......@@ -428,9 +469,9 @@ class StrutStyle extends Diagnosticable {
/// Whether the strut height should be forced.
///
/// When true, all lines will be laid out with the height of the
/// strut. All line and run-specific metrics will be ignored/overridden and only strut
/// metrics will be used instead. This property guarantees uniform line spacing, however
/// text in adjacent lines may overlap.
/// strut. All line and run-specific metrics will be ignored/overridden
/// and only strut metrics will be used instead. This property guarantees
/// uniform line spacing, however text in adjacent lines may overlap.
///
/// This property should be enabled with caution as
/// it bypasses a large portion of the vertical layout system.
......@@ -473,12 +514,12 @@ class StrutStyle extends Diagnosticable {
return RenderComparison.identical;
}
/// Returns a new strut style that inherits its null values from corresponding
/// properties in the [other] [TextStyle].
/// Returns a new strut style that inherits its null values from
/// corresponding properties in the [other] [TextStyle].
///
/// The "missing" properties of the this strut style are _filled_ by the properties
/// of the provided [TextStyle]. This is possible because [StrutStyle] shares many of
/// the same basic properties as [TextStyle].
/// The "missing" properties of the this strut style are _filled_ by
/// the properties of the provided [TextStyle]. This is possible because
/// [StrutStyle] shares many of the same basic properties as [TextStyle].
///
/// If the given text style is null, returns this strut style.
StrutStyle inheritFromTextStyle(TextStyle other) {
......
packages/flutter/lib/src/painting/text_style.dart
View file @ 9c1783e9
......@@ -106,18 +106,38 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a
///
/// ### Line height
///
/// By default, text will layout with line height as defined by the font.
/// Font-metrics defined line height may be taller or shorter than the font size.
/// The [height] property allows manual adjustment of the height of the line as
/// a multiple of [fontSize]. For most fonts, setting [height] to 1.0 is not
/// the same as omitting or setting height to null. The following diagram
/// illustrates the difference between the font-metrics defined line height and
/// the line height produced with `height: 1.0` (also known as the EM-square):
///
/// ![Text height diagram](https://flutter.github.io/assets-for-api-docs/assets/painting/text_height_diagram.png)
///
/// {@tool sample}
/// The [height] property can be used to change the line height. Here, the line
/// height is set to 5 times the font size, so that the text is very spaced out.
/// Since the `fontSize` is set to 10, the final height of the line is
/// 50 pixels.
///
/// ```dart
/// Text(
/// 'Don\'t act surprised, you guys, cuz I wrote \'em!',
/// style: TextStyle(height: 5.0),
/// style: TextStyle(fontSize: 10, height: 5.0),
/// )
/// ```
/// {@end-tool}
///
/// {@tool sample}
///
/// Examples of the resulting heights from different values of `TextStyle.height`:
///
/// ![Text height comparison diagram](https://flutter.github.io/assets-for-api-docs/assets/painting/text_height_comparison_diagram.png)
///
/// {@end-tool}
///
/// ### Wavy red underline with black text
///
/// {@tool sample}
......@@ -439,9 +459,28 @@ class TextStyle extends Diagnosticable {
/// The height of this text span, as a multiple of the font size.
///
/// If applied to the root [TextSpan], this value sets the line height, which
/// is the minimum distance between subsequent text baselines, as multiple of
/// the font size.
/// When [height] is null or omitted, the line height will be determined
/// by the font's metrics directly, which may differ from the fontSize.
/// When [height] is non-null, the line height of the span of text will be a
/// multiple of [fontSize] and be exactly `fontSize * height` logical pixels
/// tall.
///
/// For most fonts, setting [height] to 1.0 is not the same as omitting or
/// setting height to null because the [fontSize] sets the height of the EM-square,
/// which is different than the font provided metrics for line height. The
/// following diagram illustrates the difference between the font-metrics
/// defined line height and the line height produced with `height: 1.0`
/// (which forms the upper and lower edges of the EM-square):
///
/// ![Text height diagram](https://flutter.github.io/assets-for-api-docs/assets/painting/text_height_diagram.png)
///
/// {@tool sample}
///
/// Examples of the resulting line heights from different values of `TextStyle.height`:
///
/// ![Text height comparison diagram](https://flutter.github.io/assets-for-api-docs/assets/painting/text_height_comparison_diagram.png)
///
/// {@end-tool}
final double height;
/// The locale used to select region-specific glyphs.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

HIAST - GitLab