From ddd31bcee74c2da986f9764f1af31ae50b3c3557 Mon Sep 17 00:00:00 2001 From: Ian Hickson Date: Wed, 28 Aug 2019 14:41:09 -0700 Subject: [PATCH] Better docs for text (#38922) --- .../flutter/lib/src/painting/basic_types.dart | 1 + .../flutter/lib/src/painting/inline_span.dart | 3 +- .../lib/src/painting/placeholder_span.dart | 3 +- .../lib/src/painting/text_painter.dart | 2 +- .../flutter/lib/src/painting/text_span.dart | 20 ++-- .../flutter/lib/src/painting/text_style.dart | 101 +++++++++++------- .../flutter/test/material/theme_test.dart | 4 +- 7 files changed, 78 insertions(+), 56 deletions(-) diff --git a/packages/flutter/lib/src/painting/basic_types.dart b/packages/flutter/lib/src/painting/basic_types.dart index 7815f34953..65bdc53102 100644 --- a/packages/flutter/lib/src/painting/basic_types.dart +++ b/packages/flutter/lib/src/painting/basic_types.dart @@ -12,6 +12,7 @@ export 'dart:ui' show Color, ColorFilter, FilterQuality, + FontFeature, FontStyle, FontWeight, ImageShader, diff --git a/packages/flutter/lib/src/painting/inline_span.dart b/packages/flutter/lib/src/painting/inline_span.dart index ccbca2eda8..95b7246336 100644 --- a/packages/flutter/lib/src/painting/inline_span.dart +++ b/packages/flutter/lib/src/painting/inline_span.dart @@ -137,8 +137,7 @@ class InlineSpanSemanticsInformation { /// /// See also: /// -/// * [Text], a widget for showing uniformly-styled text. -/// * [RichText], a widget for finer control of text rendering. +/// * [Text], a widget for showing text. /// * [TextPainter], a class for painting [InlineSpan] objects on a [Canvas]. @immutable abstract class InlineSpan extends DiagnosticableTree { diff --git a/packages/flutter/lib/src/painting/placeholder_span.dart b/packages/flutter/lib/src/painting/placeholder_span.dart index 417ed7ae98..3b7d2017da 100644 --- a/packages/flutter/lib/src/painting/placeholder_span.dart +++ b/packages/flutter/lib/src/painting/placeholder_span.dart @@ -26,8 +26,7 @@ import 'text_style.dart'; /// /// * [WidgetSpan], a leaf node that represents an embedded inline widget. /// * [TextSpan], a node that represents text in a [TextSpan] tree. -/// * [Text], a widget for showing uniformly-styled text. -/// * [RichText], a widget for finer control of text rendering. +/// * [Text], a widget for showing text. /// * [TextPainter], a class for painting [TextSpan] objects on a [Canvas]. abstract class PlaceholderSpan extends InlineSpan { /// Creates a [PlaceholderSpan] with the given values. diff --git a/packages/flutter/lib/src/painting/text_painter.dart b/packages/flutter/lib/src/painting/text_painter.dart index 227cd760c1..3b51717781 100644 --- a/packages/flutter/lib/src/painting/text_painter.dart +++ b/packages/flutter/lib/src/painting/text_painter.dart @@ -30,7 +30,7 @@ export 'package:flutter/services.dart' show TextRange, TextSelection; /// * [WidgetSpan], a subclass of [InlineSpan] and [PlaceholderSpan] that /// represents an inline widget embedded within text. The space this /// widget takes is indicated by a placeholder. -/// * [RichText], a text widget that supports text inline widgets. +/// * [Text], a text widget that supports text inline widgets. @immutable class PlaceholderDimensions { /// Constructs a [PlaceholderDimensions] with the specified parameters. diff --git a/packages/flutter/lib/src/painting/text_span.dart b/packages/flutter/lib/src/painting/text_span.dart index c71ba172ac..5f2def3dd4 100644 --- a/packages/flutter/lib/src/painting/text_span.dart +++ b/packages/flutter/lib/src/painting/text_span.dart @@ -28,8 +28,7 @@ import 'text_style.dart'; /// tree with a list of children. /// /// To paint a [TextSpan] on a [Canvas], use a [TextPainter]. To display a text -/// span in a widget, use a [RichText]. For text with a single style, consider -/// using the [Text] widget. +/// span in a widget, use a [Text] widget. /// /// {@tool sample} /// @@ -57,8 +56,7 @@ import 'text_style.dart'; /// in an [InlineSpan] tree. Specify a widget within the [children] /// list by wrapping the widget with a [WidgetSpan]. The widget will be /// laid out inline within the paragraph. -/// * [Text], a widget for showing uniformly-styled text. -/// * [RichText], a widget for finer control of text rendering. +/// * [Text], a widget for showing text. /// * [TextPainter], a class for painting [TextSpan] objects on a [Canvas]. @immutable class TextSpan extends InlineSpan { @@ -102,9 +100,10 @@ class TextSpan extends InlineSpan { /// object that manages the [InlineSpan] painting is also responsible for /// dispatching events. In the rendering library, that is the /// [RenderParagraph] object, which corresponds to the [RichText] widget in - /// the widgets layer; these objects do not bubble events in [InlineSpan]s, so a - /// [recognizer] is only effective for events that directly hit the [text] of - /// that [InlineSpan], not any of its [children]. + /// the widgets layer (generally used via the [Text] widget); these objects do + /// not bubble events in [InlineSpan]s, so a [recognizer] is only effective + /// for events that directly hit the [text] of that [InlineSpan], not any of + /// its [children]. /// /// [InlineSpan] also does not manage the lifetime of the gesture recognizer. /// The code that owns the [GestureRecognizer] object must call @@ -113,10 +112,11 @@ class TextSpan extends InlineSpan { /// {@tool sample} /// /// This example shows how to manage the lifetime of a gesture recognizer - /// provided to an [InlineSpan] object. It defines a `BuzzingText` widget which - /// uses the [HapticFeedback] class to vibrate the device when the user + /// provided to an [InlineSpan] object. It defines a `BuzzingText` widget + /// which uses the [HapticFeedback] class to vibrate the device when the user /// long-presses the "find the" span, which is underlined in wavy green. The - /// hit-testing is handled by the [RichText] widget. + /// hit-testing is handled by the [RichText] widget which underpins the [Text] + /// widget's implementation. /// /// ```dart /// class BuzzingText extends StatefulWidget { diff --git a/packages/flutter/lib/src/painting/text_style.dart b/packages/flutter/lib/src/painting/text_style.dart index 4ab45452b6..c0723a7581 100644 --- a/packages/flutter/lib/src/painting/text_style.dart +++ b/packages/flutter/lib/src/painting/text_style.dart @@ -2,7 +2,7 @@ // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. -import 'dart:ui' as ui show ParagraphStyle, TextStyle, StrutStyle, lerpDouble, Shadow, FontFeature; +import 'dart:ui' as ui show ParagraphStyle, TextStyle, StrutStyle, lerpDouble, Shadow; import 'package:flutter/foundation.dart'; @@ -23,7 +23,7 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a /// An immutable style in which paint text. /// -/// ### Bold +/// ## Bold /// /// {@tool sample} /// Here, a single line of text in a [Text] widget is given a specific style @@ -40,11 +40,10 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a /// ``` /// {@end-tool} /// -/// ### Italics +/// ## Italics /// /// {@tool sample} -/// As in the previous example, the [Text] widget is given a specific style -/// override which is implicitly mixed with the ambient [DefaultTextStyle]. +/// In this example, the font style is adjusted to select italics. /// /// ![An example using TextStyle to create italic text](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_italics.png) /// @@ -56,28 +55,23 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a /// ``` /// {@end-tool} /// -/// ### Opacity and Color +/// ## Opacity and Color /// -/// Each line here is progressively more opaque. The base color is -/// [material.Colors.black], and [Color.withOpacity] is used to create a -/// derivative color with the desired opacity. The root [TextSpan] for this -/// [RichText] widget is explicitly given the ambient [DefaultTextStyle], since -/// [RichText] does not do that automatically. The inner [TextStyle] objects are -/// implicitly mixed with the parent [TextSpan]'s [TextSpan.style]. -/// -/// If [color] is specified, [foreground] must be null and vice versa. [color] is -/// treated as a shorthand for `Paint()..color = color`. +/// If [color] is specified, [foreground] must be null and vice versa. The +/// [color] property is treated as a shorthand for `Paint()..color = color`. /// /// If [backgroundColor] is specified, [background] must be null and vice versa. /// The [backgroundColor] is treated as a shorthand for /// `background: Paint()..color = backgroundColor`. /// -/// ![An example using TextStyle to change the text opacity and color](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_opacity_and_color.png) +/// {@tool sample} +/// Each line in this example is progressively more opaque. The base color is +/// [material.Colors.black], and [Color.withOpacity] is used to create a +/// derivative color with the desired opacity. /// /// ```dart -/// RichText( -/// text: TextSpan( -/// style: DefaultTextStyle.of(context).style, +/// Text.rich( +/// TextSpan( /// children: [ /// TextSpan( /// text: 'You don\'t have the votes.\n', @@ -96,7 +90,10 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a /// ) /// ``` /// -/// ### Size +/// ![](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_opacity_and_color.png) +/// {@end-tool} +/// +/// ## Size /// /// {@tool sample} /// In this example, the ambient [DefaultTextStyle] is explicitly manipulated to @@ -112,7 +109,7 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a /// ``` /// {@end-tool} /// -/// ### Line height +/// ## 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. @@ -140,24 +137,21 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a /// /// 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) +/// ![For Roboto, with a fontSize of 50 pixels, if the height is set to null, the line ends up 59 pixels high. Setting the height to 1.0, on the other hand, changes the line's actual height to 50 pixels. Setting the height to 2.0 changes the line's actual height to 100 pixels.](https://flutter.github.io/assets-for-api-docs/assets/painting/text_height_comparison_diagram.png) /// /// See [StrutStyle] for further control of line height at the paragraph level. /// -/// ### Wavy red underline with black text +/// ## Wavy red underline with black text /// /// {@tool sample} /// Styles can be combined. In this example, the misspelt word is drawn in black -/// text and underlined with a wavy red line to indicate a spelling error. (The -/// remainder is styled according to the Flutter default text styles, not the -/// ambient [DefaultTextStyle], since no explicit style is given and [RichText] -/// does not automatically use the ambient [DefaultTextStyle].) +/// text and underlined with a wavy red line to indicate a spelling error. /// /// ![An example using TextStyle to highlight a word with a red wavy underline](https://flutter.github.io/assets-for-api-docs/assets/painting/text_style_wavy_red_underline.png) /// /// ```dart -/// RichText( -/// text: TextSpan( +/// Text.rich( +/// TextSpan( /// text: 'Don\'t tax the South ', /// children: [ /// TextSpan( @@ -178,7 +172,7 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a /// ``` /// {@end-tool} /// -/// ### Borders and stroke (Foreground) +/// ## Borders and stroke (Foreground) /// /// {@tool sample} /// To create bordered text, a [Paint] with [Paint.style] set to [PaintingStyle.stroke] @@ -214,7 +208,7 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a /// ``` /// {@end-tool} /// -/// ### Gradients (Foreground) +/// ## Gradients (Foreground) /// /// {@tool sample} /// The [foreground] property also allows effects such as gradients to be @@ -242,7 +236,31 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a /// ``` /// {@end-tool} /// -/// ### Custom Fonts +/// ## Font features +/// +/// Some fonts can be configured in quite fine detail. To provide access to +/// these configuration options, [FontFeature] tags can be specified using the +/// [fontFeatures] property. +/// +/// {@tool sample} +/// In this example, the fictional font "JeffersonCombined" is known to contain +/// both roman and italics characters, and the italics characters are selected +/// using the `ital` font feature. +/// +/// ```dart +/// Text.rich( +/// TextSpan( +/// text: 'In Virginia, we plant seeds in the ground', +/// style: TextStyle( +/// fontFamily: 'JeffersonCombined', +/// fontFeatures: [const FontFeature.enable('ital')], +/// ), +/// ), +/// ) +/// ``` +/// {@end-tool} +/// +/// ## Custom Fonts /// /// Custom fonts can be declared in the `pubspec.yaml` file as shown below: /// @@ -288,9 +306,11 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a /// `pubspec.yaml` of a package named `my_package` which the app depends on. /// Then creating the TextStyle is done as follows: /// +/// {@tool sample} /// ```dart /// const TextStyle(fontFamily: 'Raleway', package: 'my_package') /// ``` +/// {@end-tool} /// /// If the package internally uses the font it defines, it should still specify /// the `package` argument when creating the text style as in the example above. @@ -381,14 +401,12 @@ const String _kColorBackgroundWarning = 'Cannot provide both a backgroundColor a /// /// See also: /// -/// * [Text], the widget for showing text in a single style. +/// * [Text], the widget for showing text. /// * [DefaultTextStyle], the widget that specifies the default text styles for /// [Text] widgets, configured using a [TextStyle]. -/// * [RichText], the widget for showing a paragraph of mix-style text. /// * [TextSpan], the class that wraps a [TextStyle] for the purposes of -/// passing it to a [RichText]. -/// * [TextStyle](https://api.flutter.dev/flutter/dart-ui/TextStyle-class.html), the class in the [dart:ui] library. -/// +/// passing it to the [Text.rich] constructor. +/// * [ui.TextStyle], the class in the [dart:ui] library. @immutable class TextStyle extends Diagnosticable { /// Creates a text style. @@ -682,7 +700,12 @@ class TextStyle extends Diagnosticable { /// tabular numbers, or it might offer versions of the zero digit with /// and without slashes. [FontFeature]s can be used to select which of /// these variants will be used for rendering. - final List fontFeatures; + /// + /// See also: + /// + /// * , + /// which lists the standard font features. + final List fontFeatures; /// Creates a copy of this text style but with the given fields replaced with /// the new values. @@ -710,7 +733,7 @@ class TextStyle extends Diagnosticable { Paint foreground, Paint background, List shadows, - List fontFeatures, + List fontFeatures, TextDecoration decoration, Color decorationColor, TextDecorationStyle decorationStyle, diff --git a/packages/flutter/test/material/theme_test.dart b/packages/flutter/test/material/theme_test.dart index f3d90e47a1..a4acbd82b3 100644 --- a/packages/flutter/test/material/theme_test.dart +++ b/packages/flutter/test/material/theme_test.dart @@ -720,7 +720,7 @@ class _TextStyleProxy implements TextStyle { @override List get shadows => _delegate.shadows; @override - List get fontFeatures => _delegate.fontFeatures; + List get fontFeatures => _delegate.fontFeatures; @override String toString({ DiagnosticLevel minLevel = DiagnosticLevel.debug }) => @@ -783,7 +783,7 @@ class _TextStyleProxy implements TextStyle { ui.Paint foreground, ui.Paint background, List shadows, - List fontFeatures, + List fontFeatures, TextDecoration decoration, Color decorationColor, TextDecorationStyle decorationStyle,