Unverified Commit e661ed3a authored by Greg Price's avatar Greg Price Committed by GitHub

Revise tooltip theme docs, including more cross-references (#137316)

Much of the new wording here is borrowed from [ChipTheme], [SliderTheme], or [RadioThemeData], which I think are pretty good. I believe a lot of other theme classes have similar wording too. I've also made some tweaks of my own, notably the references to [MaterialApp.theme].

This started from a desire to have clearer cross-references pointing at what to do with a FooThemeData to make it take effect:
  https://github.com/flutter/flutter/pull/135879#discussion_r1355851481
but then as I started writing I kept finding more and more small things I wanted to adjust, including a couple of bits that were extraneous or obsolete.
parent 5d48b5c8
...@@ -12,20 +12,23 @@ import 'theme.dart'; ...@@ -12,20 +12,23 @@ import 'theme.dart';
// Examples can assume: // Examples can assume:
// late BuildContext context; // late BuildContext context;
/// Defines the visual properties of [Tooltip] widgets. /// Defines the visual properties of [Tooltip] widgets, a tooltip theme.
/// ///
/// Used by [TooltipTheme] to control the visual properties of tooltips in a /// Each property of [TooltipThemeData] corresponds to a property of [Tooltip],
/// widget subtree. /// and describes the value to use when the [Tooltip] property is
/// not given an explicit non-null value.
/// ///
/// To obtain this configuration, use [TooltipTheme.of] to access the closest /// Use this class to configure a [TooltipTheme] widget, or to set the
/// ancestor [TooltipTheme] of the current [BuildContext]. /// [ThemeData.tooltipTheme] for a [Theme] widget or [MaterialApp.theme].
///
/// To obtain the current ambient tooltip theme, use [TooltipTheme.of].
/// ///
/// See also: /// See also:
/// ///
/// * [TooltipTheme], an [InheritedWidget] that propagates the theme down its /// * [TooltipTheme], a widget which overrides the tooltip theme for a subtree.
/// subtree. /// * [ThemeData.tooltipTheme], which specifies a tooltip theme as part of
/// * [TooltipThemeData], which describes the actual configuration of a /// an overall theme.
/// tooltip theme. /// * [MaterialApp.theme], which specifies a theme for the whole application.
@immutable @immutable
class TooltipThemeData with Diagnosticable { class TooltipThemeData with Diagnosticable {
/// Creates the set of properties used to configure [Tooltip]s. /// Creates the set of properties used to configure [Tooltip]s.
...@@ -237,11 +240,13 @@ class TooltipThemeData with Diagnosticable { ...@@ -237,11 +240,13 @@ class TooltipThemeData with Diagnosticable {
} }
} }
/// An inherited widget that defines the configuration for /// Applies a tooltip theme to descendant [Tooltip] widgets.
/// [Tooltip]s in this widget's subtree. ///
/// A tooltip theme describes the values to use for [Tooltip] properties
/// that are not given an explicit non-null value.
/// ///
/// Values specified here are used for [Tooltip] properties that are not /// Descendant widgets obtain the ambient tooltip theme, a [TooltipThemeData],
/// given an explicit non-null value. /// using [TooltipTheme.of].
/// ///
/// {@tool snippet} /// {@tool snippet}
/// ///
...@@ -270,6 +275,8 @@ class TooltipThemeData with Diagnosticable { ...@@ -270,6 +275,8 @@ class TooltipThemeData with Diagnosticable {
/// ///
/// See also: /// See also:
/// ///
/// * [TooltipThemeData], which describes the actual configuration of a
/// tooltip theme.
/// * [TooltipVisibility], which can be used to visually disable descendant [Tooltip]s. /// * [TooltipVisibility], which can be used to visually disable descendant [Tooltip]s.
class TooltipTheme extends InheritedTheme { class TooltipTheme extends InheritedTheme {
/// Creates a tooltip theme that controls the configurations for /// Creates a tooltip theme that controls the configurations for
...@@ -283,9 +290,13 @@ class TooltipTheme extends InheritedTheme { ...@@ -283,9 +290,13 @@ class TooltipTheme extends InheritedTheme {
/// The properties for descendant [Tooltip] widgets. /// The properties for descendant [Tooltip] widgets.
final TooltipThemeData data; final TooltipThemeData data;
/// Returns the [data] from the closest [TooltipTheme] ancestor. If there is /// Returns the ambient tooltip theme.
/// no ancestor, it returns [ThemeData.tooltipTheme]. Applications can assume ///
/// that the returned value will not be null. /// The result comes from the closest [TooltipTheme] ancestor if any,
/// and otherwise from [Theme.of] and [ThemeData.tooltipTheme].
///
/// When a widget uses this method, it is automatically rebuilt if the
/// tooltip theme later changes, so that the changes can be applied.
/// ///
/// Typical usage is as follows: /// Typical usage is as follows:
/// ///
......
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