Revert "Better docs for text (#38922)" (#39447)
This reverts commit ddd31bcee74c2da986f9764f1af31ae50b3c3557.
diff --git a/packages/flutter/lib/src/painting/basic_types.dart b/packages/flutter/lib/src/painting/basic_types.dart
index 65bdc53..7815f34 100644
--- a/packages/flutter/lib/src/painting/basic_types.dart
+++ b/packages/flutter/lib/src/painting/basic_types.dart
@@ -12,7 +12,6 @@
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 95b7246..ccbca2e 100644
--- a/packages/flutter/lib/src/painting/inline_span.dart
+++ b/packages/flutter/lib/src/painting/inline_span.dart
@@ -137,7 +137,8 @@
///
/// See also:
///
-/// * [Text], a widget for showing text.
+/// * [Text], a widget for showing uniformly-styled text.
+/// * [RichText], a widget for finer control of text rendering.
/// * [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 3b7d201..417ed7a 100644
--- a/packages/flutter/lib/src/painting/placeholder_span.dart
+++ b/packages/flutter/lib/src/painting/placeholder_span.dart
@@ -26,7 +26,8 @@
///
/// * [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 text.
+/// * [Text], a widget for showing uniformly-styled text.
+/// * [RichText], a widget for finer control of text rendering.
/// * [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 3b51717..227cd76 100644
--- a/packages/flutter/lib/src/painting/text_painter.dart
+++ b/packages/flutter/lib/src/painting/text_painter.dart
@@ -30,7 +30,7 @@
/// * [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.
-/// * [Text], a text widget that supports text inline widgets.
+/// * [RichText], 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 5f2def3d..c71ba17 100644
--- a/packages/flutter/lib/src/painting/text_span.dart
+++ b/packages/flutter/lib/src/painting/text_span.dart
@@ -28,7 +28,8 @@
/// 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 [Text] widget.
+/// span in a widget, use a [RichText]. For text with a single style, consider
+/// using the [Text] widget.
///
/// {@tool sample}
///
@@ -56,7 +57,8 @@
/// 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 text.
+/// * [Text], a widget for showing uniformly-styled text.
+/// * [RichText], a widget for finer control of text rendering.
/// * [TextPainter], a class for painting [TextSpan] objects on a [Canvas].
@immutable
class TextSpan extends InlineSpan {
@@ -100,10 +102,9 @@
/// 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 (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].
+ /// 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].
///
/// [InlineSpan] also does not manage the lifetime of the gesture recognizer.
/// The code that owns the [GestureRecognizer] object must call
@@ -112,11 +113,10 @@
/// {@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 which underpins the [Text]
- /// widget's implementation.
+ /// hit-testing is handled by the [RichText] widget.
///
/// ```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 c0723a7..4ab4545 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;
+import 'dart:ui' as ui show ParagraphStyle, TextStyle, StrutStyle, lerpDouble, Shadow, FontFeature;
import 'package:flutter/foundation.dart';
@@ -23,7 +23,7 @@
/// 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,10 +40,11 @@
/// ```
/// {@end-tool}
///
-/// ## Italics
+/// ### Italics
///
/// {@tool sample}
-/// In this example, the font style is adjusted to select italics.
+/// As in the previous example, the [Text] widget is given a specific style
+/// override which is implicitly mixed with the ambient [DefaultTextStyle].
///
/// 
///
@@ -55,23 +56,28 @@
/// ```
/// {@end-tool}
///
-/// ## Opacity and Color
+/// ### Opacity and Color
///
-/// If [color] is specified, [foreground] must be null and vice versa. The
-/// [color] property is treated as a shorthand for `Paint()..color = 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 [backgroundColor] is specified, [background] must be null and vice versa.
/// The [backgroundColor] is treated as a shorthand for
/// `background: Paint()..color = backgroundColor`.
///
-/// {@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
-/// Text.rich(
-/// TextSpan(
+/// RichText(
+/// text: TextSpan(
+/// style: DefaultTextStyle.of(context).style,
/// children: <TextSpan>[
/// TextSpan(
/// text: 'You don\'t have the votes.\n',
@@ -90,10 +96,7 @@
/// )
/// ```
///
-/// 
-/// {@end-tool}
-///
-/// ## Size
+/// ### Size
///
/// {@tool sample}
/// In this example, the ambient [DefaultTextStyle] is explicitly manipulated to
@@ -109,7 +112,7 @@
/// ```
/// {@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.
@@ -137,21 +140,24 @@
///
/// Examples of the resulting heights from different values of `TextStyle.height`:
///
-/// 
+/// 
///
/// 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.
+/// 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].)
///
/// 
///
/// ```dart
-/// Text.rich(
-/// TextSpan(
+/// RichText(
+/// text: TextSpan(
/// text: 'Don\'t tax the South ',
/// children: <TextSpan>[
/// TextSpan(
@@ -172,7 +178,7 @@
/// ```
/// {@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]
@@ -208,7 +214,7 @@
/// ```
/// {@end-tool}
///
-/// ## Gradients (Foreground)
+/// ### Gradients (Foreground)
///
/// {@tool sample}
/// The [foreground] property also allows effects such as gradients to be
@@ -236,31 +242,7 @@
/// ```
/// {@end-tool}
///
-/// ## 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
///
/// Custom fonts can be declared in the `pubspec.yaml` file as shown below:
///
@@ -306,11 +288,9 @@
/// `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.
@@ -401,12 +381,14 @@
///
/// See also:
///
-/// * [Text], the widget for showing text.
+/// * [Text], the widget for showing text in a single style.
/// * [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 the [Text.rich] constructor.
-/// * [ui.TextStyle], the class in the [dart:ui] library.
+/// passing it to a [RichText].
+/// * [TextStyle](https://api.flutter.dev/flutter/dart-ui/TextStyle-class.html), the class in the [dart:ui] library.
+///
@immutable
class TextStyle extends Diagnosticable {
/// Creates a text style.
@@ -700,12 +682,7 @@
/// 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.
- ///
- /// See also:
- ///
- /// * <https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist>,
- /// which lists the standard font features.
- final List<FontFeature> fontFeatures;
+ final List<ui.FontFeature> fontFeatures;
/// Creates a copy of this text style but with the given fields replaced with
/// the new values.
@@ -733,7 +710,7 @@
Paint foreground,
Paint background,
List<ui.Shadow> shadows,
- List<FontFeature> fontFeatures,
+ List<ui.FontFeature> 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 a4acbd8..f3d90e4 100644
--- a/packages/flutter/test/material/theme_test.dart
+++ b/packages/flutter/test/material/theme_test.dart
@@ -720,7 +720,7 @@
@override
List<Shadow> get shadows => _delegate.shadows;
@override
- List<FontFeature> get fontFeatures => _delegate.fontFeatures;
+ List<ui.FontFeature> get fontFeatures => _delegate.fontFeatures;
@override
String toString({ DiagnosticLevel minLevel = DiagnosticLevel.debug }) =>
@@ -783,7 +783,7 @@
ui.Paint foreground,
ui.Paint background,
List<Shadow> shadows,
- List<FontFeature> fontFeatures,
+ List<ui.FontFeature> fontFeatures,
TextDecoration decoration,
Color decorationColor,
TextDecorationStyle decorationStyle,
