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';
// Examples can assume:
// 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
/// widget subtree.
/// Each property of [TooltipThemeData] corresponds to a property of [Tooltip],
/// 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
/// ancestor [TooltipTheme] of the current [BuildContext].
/// Use this class to configure a [TooltipTheme] widget, or to set the
/// [ThemeData.tooltipTheme] for a [Theme] widget or [MaterialApp.theme].
///
/// To obtain the current ambient tooltip theme, use [TooltipTheme.of].
///
/// See also:
///
/// * [TooltipTheme], an [InheritedWidget] that propagates the theme down its
/// subtree.
/// * [TooltipThemeData], which describes the actual configuration of a
/// tooltip theme.
/// * [TooltipTheme], a widget which overrides the tooltip theme for a subtree.
/// * [ThemeData.tooltipTheme], which specifies a tooltip theme as part of
/// an overall theme.
/// * [MaterialApp.theme], which specifies a theme for the whole application.
@immutable
class TooltipThemeData with Diagnosticable {
/// Creates the set of properties used to configure [Tooltip]s.
......@@ -237,11 +240,13 @@ class TooltipThemeData with Diagnosticable {
}
}
/// An inherited widget that defines the configuration for
/// [Tooltip]s in this widget's subtree.
/// Applies a tooltip theme to descendant [Tooltip] widgets.
///
/// 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
/// given an explicit non-null value.
/// Descendant widgets obtain the ambient tooltip theme, a [TooltipThemeData],
/// using [TooltipTheme.of].
///
/// {@tool snippet}
///
......@@ -270,6 +275,8 @@ class TooltipThemeData with Diagnosticable {
///
/// See also:
///
/// * [TooltipThemeData], which describes the actual configuration of a
/// tooltip theme.
/// * [TooltipVisibility], which can be used to visually disable descendant [Tooltip]s.
class TooltipTheme extends InheritedTheme {
/// Creates a tooltip theme that controls the configurations for
......@@ -283,9 +290,13 @@ class TooltipTheme extends InheritedTheme {
/// The properties for descendant [Tooltip] widgets.
final TooltipThemeData data;
/// Returns the [data] from the closest [TooltipTheme] ancestor. If there is
/// no ancestor, it returns [ThemeData.tooltipTheme]. Applications can assume
/// that the returned value will not be null.
/// Returns the ambient tooltip theme.
///
/// 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:
///
......
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