diff --git a/packages/flutter/lib/src/material/app_bar.dart b/packages/flutter/lib/src/material/app_bar.dart index 195e0235de2..9c7142a0963 100644 --- a/packages/flutter/lib/src/material/app_bar.dart +++ b/packages/flutter/lib/src/material/app_bar.dart @@ -152,6 +152,7 @@ class _PreferredAppBarSize extends Size { /// * [FlexibleSpaceBar], which is used with [flexibleSpace] when the app bar /// can expand and collapse. /// * +/// * /// * Cookbook: [Place a floating app bar above a list](https://flutter.dev/docs/cookbook/lists/floating-app-bar) class AppBar extends StatefulWidget implements PreferredSizeWidget { /// Creates a Material Design app bar. diff --git a/packages/flutter/lib/src/material/bottom_navigation_bar.dart b/packages/flutter/lib/src/material/bottom_navigation_bar.dart index ca0c9c54b64..4880f8237cc 100644 --- a/packages/flutter/lib/src/material/bottom_navigation_bar.dart +++ b/packages/flutter/lib/src/material/bottom_navigation_bar.dart @@ -123,6 +123,7 @@ enum BottomNavigationBarLandscapeLayout { /// * [BottomNavigationBarItem] /// * [Scaffold] /// * +/// * [NavigationBar], this widget's replacement in Material Design 3. class BottomNavigationBar extends StatefulWidget { /// Creates a bottom navigation bar which is typically used as a /// [Scaffold]'s [Scaffold.bottomNavigationBar] argument. diff --git a/packages/flutter/lib/src/material/card.dart b/packages/flutter/lib/src/material/card.dart index f98847e2ff3..f06d9565b2d 100644 --- a/packages/flutter/lib/src/material/card.dart +++ b/packages/flutter/lib/src/material/card.dart @@ -53,6 +53,7 @@ import 'theme.dart'; /// * [ListTile], to display icons and text in a card. /// * [showDialog], to display a modal card. /// * +/// * class Card extends StatelessWidget { /// Creates a Material Design card. /// diff --git a/packages/flutter/lib/src/material/dialog.dart b/packages/flutter/lib/src/material/dialog.dart index 5fbbe9a18c2..90fc84270a3 100644 --- a/packages/flutter/lib/src/material/dialog.dart +++ b/packages/flutter/lib/src/material/dialog.dart @@ -169,10 +169,10 @@ class Dialog extends StatelessWidget { /// A Material Design alert dialog. /// -/// An alert dialog informs the user about situations that require -/// acknowledgement. An alert dialog has an optional title and an optional list -/// of actions. The title is displayed above the content and the actions are -/// displayed below the content. +/// An alert dialog (also known as a basic dialog) informs the user about +/// situations that require acknowledgement. An alert dialog has an optional +/// title and an optional list of actions. The title is displayed above the +/// content and the actions are displayed below the content. /// /// {@youtube 560 315 https://www.youtube.com/watch?v=75CsnyRXf5I} /// @@ -251,6 +251,7 @@ class Dialog extends StatelessWidget { /// * [CupertinoAlertDialog], an iOS-styled alert dialog. /// * [showDialog], which actually displays the dialog and returns its result. /// * +/// * class AlertDialog extends StatelessWidget { /// Creates an alert dialog. /// @@ -1060,6 +1061,7 @@ Widget _buildMaterialDialogTransitions(BuildContext context, Animation a /// * [DisplayFeatureSubScreen], which documents the specifics of how /// [DisplayFeature]s can split the screen into sub-screens. /// * +/// * Future showDialog({ required BuildContext context, required WidgetBuilder builder, diff --git a/packages/flutter/lib/src/material/elevated_button.dart b/packages/flutter/lib/src/material/elevated_button.dart index 819adf19266..6d9708b7bb6 100644 --- a/packages/flutter/lib/src/material/elevated_button.dart +++ b/packages/flutter/lib/src/material/elevated_button.dart @@ -57,6 +57,7 @@ import 'theme_data.dart'; /// * [TextButton], a simple flat button without a shadow. /// * [OutlinedButton], a [TextButton] with a border outline. /// * +/// * class ElevatedButton extends ButtonStyleButton { /// Create an ElevatedButton. /// diff --git a/packages/flutter/lib/src/material/floating_action_button.dart b/packages/flutter/lib/src/material/floating_action_button.dart index 599dee3da6a..b184981a559 100644 --- a/packages/flutter/lib/src/material/floating_action_button.dart +++ b/packages/flutter/lib/src/material/floating_action_button.dart @@ -89,6 +89,7 @@ enum _FloatingActionButtonType { /// * [Scaffold], in which floating action buttons typically live. /// * [ElevatedButton], a filled button whose material elevates when pressed. /// * +/// * class FloatingActionButton extends StatelessWidget { /// Creates a circular floating action button. /// @@ -235,6 +236,9 @@ class FloatingActionButton extends StatelessWidget { /// The [label], [autofocus], and [clipBehavior] arguments must not be null. /// Additionally, [elevation], [highlightElevation], and [disabledElevation] /// (if specified) must be non-negative. + /// + /// See also: + /// * const FloatingActionButton.extended({ super.key, this.tooltip, diff --git a/packages/flutter/lib/src/material/list_tile.dart b/packages/flutter/lib/src/material/list_tile.dart index 7fd627bc20c..9795398d957 100644 --- a/packages/flutter/lib/src/material/list_tile.dart +++ b/packages/flutter/lib/src/material/list_tile.dart @@ -291,6 +291,7 @@ enum ListTileControlAffinity { /// * /// * Cookbook: [Use lists](https://flutter.dev/docs/cookbook/lists/basic-list) /// * Cookbook: [Implement swipe to dismiss](https://flutter.dev/docs/cookbook/gestures/dismissible) +// TODO(plg): Add link to m3 spec below m2 spec link when available class ListTile extends StatelessWidget { /// Creates a list tile. /// diff --git a/packages/flutter/lib/src/material/material.dart b/packages/flutter/lib/src/material/material.dart index f3ffb8b1a05..284471b8ee4 100644 --- a/packages/flutter/lib/src/material/material.dart +++ b/packages/flutter/lib/src/material/material.dart @@ -164,6 +164,7 @@ abstract class MaterialInkController { /// * [MergeableMaterial], a piece of material that can split and re-merge. /// * [Card], a wrapper for a [Material] of [type] [MaterialType.card]. /// * +/// * class Material extends StatefulWidget { /// Creates a piece of material. /// diff --git a/packages/flutter/lib/src/material/navigation_bar.dart b/packages/flutter/lib/src/material/navigation_bar.dart index 2039eb735b0..600a3deeb50 100644 --- a/packages/flutter/lib/src/material/navigation_bar.dart +++ b/packages/flutter/lib/src/material/navigation_bar.dart @@ -48,6 +48,7 @@ import 'tooltip.dart'; /// * [NavigationDestination] /// * [BottomNavigationBar] /// * +/// * class NavigationBar extends StatelessWidget { /// Creates a Material 3 Navigation Bar component. /// diff --git a/packages/flutter/lib/src/material/navigation_rail.dart b/packages/flutter/lib/src/material/navigation_rail.dart index ba65683da18..c61f04d604f 100644 --- a/packages/flutter/lib/src/material/navigation_rail.dart +++ b/packages/flutter/lib/src/material/navigation_rail.dart @@ -61,7 +61,8 @@ import 'theme.dart'; /// destinations in the navigation rail. /// * [BottomNavigationBar], which is a similar navigation widget that's laid /// out horizontally. -/// * https://material.io/components/navigation-rail/ +/// * +/// * class NavigationRail extends StatefulWidget { /// Creates a Material Design navigation rail. /// diff --git a/packages/flutter/lib/src/material/outlined_button.dart b/packages/flutter/lib/src/material/outlined_button.dart index f9bf0467fab..6c2669fb2ac 100644 --- a/packages/flutter/lib/src/material/outlined_button.dart +++ b/packages/flutter/lib/src/material/outlined_button.dart @@ -62,6 +62,7 @@ import 'theme_data.dart'; /// * [ElevatedButton], a filled Material Design button with a shadow. /// * [TextButton], a Material Design button without a shadow. /// * +/// * class OutlinedButton extends ButtonStyleButton { /// Create an OutlinedButton. /// diff --git a/packages/flutter/lib/src/material/text_button.dart b/packages/flutter/lib/src/material/text_button.dart index a26e114b456..689155f5e4e 100644 --- a/packages/flutter/lib/src/material/text_button.dart +++ b/packages/flutter/lib/src/material/text_button.dart @@ -62,6 +62,7 @@ import 'theme_data.dart'; /// * [OutlinedButton], a [TextButton] with a border outline. /// * [ElevatedButton], a filled button whose material elevates when pressed. /// * +/// * class TextButton extends ButtonStyleButton { /// Create a TextButton. /// diff --git a/packages/flutter/lib/src/material/theme_data.dart b/packages/flutter/lib/src/material/theme_data.dart index 78a8dae7f31..4ad4eafe916 100644 --- a/packages/flutter/lib/src/material/theme_data.dart +++ b/packages/flutter/lib/src/material/theme_data.dart @@ -1133,53 +1133,63 @@ class ThemeData with Diagnosticable { /// A temporary flag used to opt-in to Material 3 features. /// - /// If true, then components that have been migrated to Material 3 will + /// If true, then widgets that have been migrated to Material 3 will /// use new colors, typography and other features of Material 3. /// If false, they will use the Material 2 look and feel. /// + /// During the migration to Material 3, turning this on may yield + /// inconsistent look and feel in your app as some widgets are migrated + /// while others have yet to be. + /// + /// Defaults to false. When the Material 3 specification is complete + /// and all widgets are migrated on stable, we will change this flag to be + /// true by default. After that change has landed on stable, we will deprecate + /// this flag and remove all uses of it. At that point, the `material` library + /// will aim to only support Material 3. + /// + /// ## Defaults /// If a [ThemeData] is constructed with [useMaterial3] set to true, then - /// some properties will get special defaults. However, just copying a [ThemeData] - /// with [useMaterial3] set to true will not change any of these properties in the - /// resulting [ThemeData]. These properties are: + /// some properties will get updated defaults. Please note that + /// [ThemeData.copyWith] with [useMaterial3] set to true will + /// not change any of these properties in the resulting [ThemeData]. + /// /// /// - /// | Property | Material 3 default | Fallback default | + /// | Property | Material 3 default | Material 2 default | /// | :-------------- | :--------------------------- | :------------------------ | /// | [typography] | [Typography.material2021] | [Typography.material2014] | /// | [splashFactory] | [InkSparkle]* or [InkRipple] | [InkSplash] | /// - /// \* if and only if the target platform is Android and the app is not + /// \* if the target platform is Android and the app is not /// running on the web, otherwise it will fallback to [InkRipple]. /// - /// During the migration to Material 3, turning this on may yield - /// inconsistent look and feel in your app. Some components will be migrated - /// before others and typography changes will be coming in stages. + /// ## Affected widgets /// - /// [useMaterial3] defaults to false. After all the migrated components - /// have landed on stable, we will change this to be true by default. After - /// that change has landed on stable, we will deprecate this flag and remove - /// all uses of it. Everything will use the Material 3 look and feel at - /// that point. + /// This flag affects styles and components. /// - /// Components that have been migrated to Material 3 are: + /// ### Styles + /// * Color: [ColorScheme], [Material] + /// * Shape: (see components below) + /// * Typography: `typography` (see table above) /// - /// * [AlertDialog] - /// * [AppBar] - /// * [Card] - /// * [Dialog] - /// * [ElevatedButton] - /// * [FloatingActionButton] - /// * [Material] - /// * [NavigationBar] (new, replacing [BottomNavigationBar]) - /// * [NavigationRail] - /// * [OutlinedButton] - /// * [StretchingOverscrollIndicator], replacing the - /// [GlowingOverscrollIndicator] - /// * [TextButton] + /// ### Components + /// * Common buttons: [TextButton], [OutlinedButton], [ElevatedButton] + /// * FAB: [FloatingActionButton] + /// * Extended FAB: [FloatingActionButton.extended] + /// * Cards: [Card] + /// * Dialogs: [Dialog], [AlertDialog] + /// * Lists: [ListTile] + /// * Navigation bar: [NavigationBar] (new, replacing [BottomNavigationBar]) + /// * [Navigation rail](https://m3.material.io/components/navigation-rail): [NavigationRail] + /// * Top app bar: [AppBar] + /// + /// In addition, this flag enables features introduced in Android 12. + /// * Stretch overscroll: [MaterialScrollBehavior] + /// * Ripple: `splashFactory` (see table above) /// /// See also: /// - /// * [Material Design 3](https://m3.material.io/). + /// * [Material 3 specification](https://m3.material.io/). final bool useMaterial3; /// The density value for specifying the compactness of various UI components. diff --git a/packages/flutter/lib/src/material/typography.dart b/packages/flutter/lib/src/material/typography.dart index d374e5024e3..4e2d00200f0 100644 --- a/packages/flutter/lib/src/material/typography.dart +++ b/packages/flutter/lib/src/material/typography.dart @@ -77,6 +77,7 @@ enum ScriptCategory { /// See also: /// /// * +/// * @immutable class Typography with Diagnosticable { /// Creates a typography instance. @@ -157,6 +158,9 @@ class Typography with Diagnosticable { /// /// The default values for [englishLike], [dense], and [tall] are /// [englishLike2021], [dense2021], and [tall2021]. + /// + /// See also: + /// * factory Typography.material2021({ TargetPlatform? platform = TargetPlatform.android, TextTheme? black,