diff --git a/packages/cupertino_ui/analysis_options.yaml b/packages/cupertino_ui/analysis_options.yaml index bd2a1b96a3d9..3e17bba73b77 100644 --- a/packages/cupertino_ui/analysis_options.yaml +++ b/packages/cupertino_ui/analysis_options.yaml @@ -13,3 +13,8 @@ analyzer: - windows/** - macos/** - linux/** + +linter: + rules: + # TODO(dkwingsmt): Remove when https://github.com/dart-lang/sdk/issues/63777 is fixed. + unintended_html_in_doc_comment: false diff --git a/packages/cupertino_ui/lib/src/activity_indicator.dart b/packages/cupertino_ui/lib/src/activity_indicator.dart index e4e2ff138070..2e418e461e5c 100644 --- a/packages/cupertino_ui/lib/src/activity_indicator.dart +++ b/packages/cupertino_ui/lib/src/activity_indicator.dart @@ -21,14 +21,17 @@ const Color _kActiveTickColor = CupertinoDynamicColor.withBrightness( /// /// {@youtube 560 315 https://www.youtube.com/watch?v=AENVH-ZqKDQ} /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how [CupertinoActivityIndicator] can be customized. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/activity_indicator/cupertino_activity_indicator.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -204,14 +207,17 @@ class _CupertinoActivityIndicatorPainter extends CustomPainter { /// The [CupertinoLinearActivityIndicator] is a linear progress bar that /// displays a colored bar to indicate the progress of an ongoing task. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how [CupertinoLinearActivityIndicator] can be customized. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/activity_indicator/cupertino_linear_activity_indicator.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/bottom_tab_bar.dart b/packages/cupertino_ui/lib/src/bottom_tab_bar.dart index aef0f1ac0516..173f7025bc34 100644 --- a/packages/cupertino_ui/lib/src/bottom_tab_bar.dart +++ b/packages/cupertino_ui/lib/src/bottom_tab_bar.dart @@ -46,14 +46,17 @@ const Color _kDefaultTabBarInactiveColor = CupertinoColors.inactiveGray; /// this behavior, wrap each of the `navigationBar`'s components inside a /// [MediaQuery] with the desired [TextScaler]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [CupertinoTabBar] placed in a [CupertinoTabScaffold]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/bottom_tab_bar/cupertino_tab_bar.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/button.dart b/packages/cupertino_ui/lib/src/button.dart index 8b4d02a5c5fe..19f577162482 100644 --- a/packages/cupertino_ui/lib/src/button.dart +++ b/packages/cupertino_ui/lib/src/button.dart @@ -58,15 +58,24 @@ enum _CupertinoButtonStyle { /// with the [CupertinoThemeData.primaryColor] (or /// [CupertinoThemeData.primaryContrastingColor] if the button is disabled). /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows produces an enabled and disabled [CupertinoButton] and /// [CupertinoButton.filled]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@template cupertino_ui.dartpad_guide} +/// +/// +/// To see it in action, copy and run this code snippet on [DartPad](https://dartpad.dev/). +/// +/// +/// {@endtemplate} +/// /// {@example /example/lib/button/cupertino_button.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/checkbox.dart b/packages/cupertino_ui/lib/src/checkbox.dart index c917fdb4aece..09710c691ffb 100644 --- a/packages/cupertino_ui/lib/src/checkbox.dart +++ b/packages/cupertino_ui/lib/src/checkbox.dart @@ -73,14 +73,17 @@ const List _kDisabledDarkGradientOpacities = [0.08, 0.14]; /// [kMinInteractiveDimensionCupertino] pixels to meet accessibility /// guidelines. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a toggleable [CupertinoCheckbox]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/checkbox/cupertino_checkbox.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/context_menu.dart b/packages/cupertino_ui/lib/src/context_menu.dart index 72e87b3b0212..ed5751e50133 100644 --- a/packages/cupertino_ui/lib/src/context_menu.dart +++ b/packages/cupertino_ui/lib/src/context_menu.dart @@ -96,25 +96,31 @@ enum _ContextMenuLocation { center, left, right } /// background or by calling `Navigator.pop(context)`. Unlike [PopupRoute], it can /// also be closed by swiping downwards. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows a very simple [CupertinoContextMenu] for the Flutter logo. /// Long press on it to open. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/context_menu/cupertino_context_menu.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows a similar CupertinoContextMenu, this time using [builder] /// to add a border radius to the widget. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/context_menu/cupertino_context_menu.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -332,8 +338,7 @@ class CupertinoContextMenu extends StatefulWidget { /// // TODO(framework): End of the blue example container. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// Additionally below is an example of a real world use case for [builder]. /// @@ -345,9 +350,13 @@ class CupertinoContextMenu extends StatefulWidget { /// like [CupertinoContextMenu.kEndBoxShadow], to match the native iOS /// animation as close as desired. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro cupertino_ui.dartpad_guide} + /// /// {@example /example/lib/context_menu/cupertino_context_menu.1.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final CupertinoContextMenuBuilder builder; // TODO(mitchgoodwin): deprecate [child] with builder refactor https://github.com/flutter/flutter/issues/116306 diff --git a/packages/cupertino_ui/lib/src/date_picker.dart b/packages/cupertino_ui/lib/src/date_picker.dart index bac359f2a314..ab84b4be848f 100644 --- a/packages/cupertino_ui/lib/src/date_picker.dart +++ b/packages/cupertino_ui/lib/src/date_picker.dart @@ -230,8 +230,7 @@ enum _PickerColumnType { /// full screen width. Content texts are shown with /// [CupertinoTextThemeData.dateTimePickerTextStyle]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to implement CupertinoDatePicker with different picker modes. /// We can provide initial dateTime value for the picker to display. When user changes @@ -239,9 +238,13 @@ enum _PickerColumnType { /// /// CupertinoDatePicker can be displayed directly on a screen or in a popup. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/date_picker/cupertino_date_picker.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -2173,14 +2176,17 @@ enum CupertinoTimerPickerMode { /// provides more space than it needs, the picker will position itself according /// to its [alignment] property. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [CupertinoTimerPicker] that returns a countdown duration. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/date_picker/cupertino_timer_picker.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/dialog.dart b/packages/cupertino_ui/lib/src/dialog.dart index 27f79c4d7c9d..7bd99725093f 100644 --- a/packages/cupertino_ui/lib/src/dialog.dart +++ b/packages/cupertino_ui/lib/src/dialog.dart @@ -213,16 +213,19 @@ bool _isInAccessibilityMode(BuildContext context) { /// Typically passed as the child widget to [showDialog], which displays the /// dialog. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to use a [CupertinoAlertDialog]. /// The [CupertinoAlertDialog] shows an alert with a set of two choices /// when [CupertinoButton] is pressed. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/dialog/cupertino_alert_dialog.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -520,16 +523,19 @@ class _CupertinoAlertDialogState extends State { /// which is useful for more complicated layouts, such as rendering divider gaps /// in [CupertinoAlertDialog] or rendering custom surface colors. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to use a [CupertinoPopupSurface]. The [CupertinoPopupSurface] /// shows a modal popup from the bottom of the screen. /// Toggle the switch to configure its surface color. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/dialog/cupertino_popup_surface.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -1058,16 +1064,19 @@ class _ActionSheetGestureDetector extends StatelessWidget { /// [showCupertinoModalPopup], which displays the action sheet by sliding it up /// from the bottom of the screen. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to use a [CupertinoActionSheet]. /// The [CupertinoActionSheet] shows a modal popup that slides in from the /// bottom when [CupertinoButton] is pressed. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/dialog/cupertino_action_sheet.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/expansion_tile.dart b/packages/cupertino_ui/lib/src/expansion_tile.dart index 162d76621d61..634a51ac9ec0 100644 --- a/packages/cupertino_ui/lib/src/expansion_tile.dart +++ b/packages/cupertino_ui/lib/src/expansion_tile.dart @@ -59,14 +59,17 @@ enum ExpansionTileTransitionMode { /// A single-line [CupertinoListTile] with an expansion arrow icon that expands /// or collapses the tile to reveal or hide the [child]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to use [CupertinoExpansionTile] with different transition modes. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/expansion_tile/cupertino_expansion_tile.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/form_row.dart b/packages/cupertino_ui/lib/src/form_row.dart index 33e90d360ca9..0a3d60eb1e7c 100644 --- a/packages/cupertino_ui/lib/src/form_row.dart +++ b/packages/cupertino_ui/lib/src/form_row.dart @@ -36,15 +36,18 @@ const EdgeInsetsGeometry _kDefaultPadding = EdgeInsetsDirectional.fromSTEB(20.0, /// be shown in [CupertinoColors.destructiveRed] coloring and /// medium-weighted font. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Creates a [CupertinoFormSection] containing a [CupertinoFormRow] with [prefix], /// [child], [helper] and [error] specified. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/form_row/cupertino_form_row.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// class CupertinoFormRow extends StatelessWidget { /// Creates an iOS-style split form row with a standard prefix and child widget. diff --git a/packages/cupertino_ui/lib/src/list_section.dart b/packages/cupertino_ui/lib/src/list_section.dart index 58283edfdf05..e0c2685e2423 100644 --- a/packages/cupertino_ui/lib/src/list_section.dart +++ b/packages/cupertino_ui/lib/src/list_section.dart @@ -161,26 +161,32 @@ enum CupertinoListSectionType { /// /// {@macro flutter.material.Material.clipBehavior} /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Creates a base [CupertinoListSection] containing [CupertinoListTile]s with /// `leading`, `title`, `additionalInfo` and `trailing` widgets. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/list_section/list_section_base.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Creates an "Inset Grouped" [CupertinoListSection] containing /// notched [CupertinoListTile]s with `leading`, `title`, `additionalInfo` and /// `trailing` widgets. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/list_section/list_section_inset.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/list_tile.dart b/packages/cupertino_ui/lib/src/list_tile.dart index 060ca933b1a0..849f882e24ce 100644 --- a/packages/cupertino_ui/lib/src/list_tile.dart +++ b/packages/cupertino_ui/lib/src/list_tile.dart @@ -78,15 +78,18 @@ enum _CupertinoListTileType { base, notched } /// behavior it should not be used for example to toggle the [CupertinoSwitch] /// in the trailing widget. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example uses a [ListView] to demonstrate different configurations of /// [CupertinoListTile]s. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/list_tile/cupertino_list_tile.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/menu_anchor.dart b/packages/cupertino_ui/lib/src/menu_anchor.dart index 762861815e0c..0d2739b8fc22 100644 --- a/packages/cupertino_ui/lib/src/menu_anchor.dart +++ b/packages/cupertino_ui/lib/src/menu_anchor.dart @@ -305,15 +305,18 @@ typedef CupertinoMenuAnimationStatusChangedCallback = void Function(AnimationSta /// // TODO(framework): End of the blue example container. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example demonstrates a [CupertinoMenuAnchor] that wraps a button and /// shows a menu with three [CupertinoMenuItem]s and one [CupertinoMenuDivider]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/menu_anchor/menu_anchor.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -1711,15 +1714,18 @@ class _CupertinoDividerPainter extends CustomPainter { /// // TODO(framework): End of the blue example container. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example demonstrates a [CupertinoMenuAnchor] that wraps a button and /// shows a menu with three [CupertinoMenuItem]s and one [CupertinoMenuDivider]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/menu_anchor/menu_anchor.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// * [CupertinoMenuAnchor], a Cupertino-style widget that shows a menu of diff --git a/packages/cupertino_ui/lib/src/nav_bar.dart b/packages/cupertino_ui/lib/src/nav_bar.dart index 85e8acd084f2..b4019e9d50f1 100644 --- a/packages/cupertino_ui/lib/src/nav_bar.dart +++ b/packages/cupertino_ui/lib/src/nav_bar.dart @@ -330,27 +330,33 @@ bool _isTransitionable(BuildContext context) { /// this behavior, wrap each of the `navigationBar`'s components inside a /// [MediaQuery] with the desired [TextScaler]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [CupertinoNavigationBar] placed in a [CupertinoPageScaffold]. /// Since [backgroundColor]'s opacity is not 1.0, there is a blur effect and /// content slides underneath. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/nav_bar/cupertino_navigation_bar.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows the resulting layout from [CupertinoNavigationBar.large] /// constructor, showing a large title similar to the expanded state of /// [CupertinoSliverNavigationBar]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/nav_bar/cupertino_navigation_bar.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -626,15 +632,18 @@ class CupertinoNavigationBar extends StatefulWidget implements ObstructingPrefer /// Only widgets that implement [PreferredSizeWidget] can be used at the /// bottom of a navigation bar. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows a [CupertinoSearchTextField] at the bottom of a /// [CupertinoNavigationBar]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro cupertino_ui.dartpad_guide} + /// /// {@example /example/lib/nav_bar/cupertino_navigation_bar.1.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// See also: /// @@ -935,23 +944,29 @@ class _CupertinoNavigationBarState extends State { /// user scrolls, but it will also stretch when the user over-scrolls if the /// [stretch] value is `true`. Defaults to `false`. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows [CupertinoSliverNavigationBar] in action inside a [CustomScrollView]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/nav_bar/cupertino_sliver_nav_bar.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// To add a widget to the bottom of the nav bar, wrap it with [PreferredSize] and provide its fully extended size. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/nav_bar/cupertino_sliver_nav_bar.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -1015,15 +1030,18 @@ class CupertinoSliverNavigationBar extends StatefulWidget { /// If [automaticallyImplyTitle] is false, then the [largeTitle] argument is /// required. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example demonstrates how to use a /// [CupertinoSliverNavigationBar.search] to manage a search view. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro cupertino_ui.dartpad_guide} + /// /// {@example /example/lib/nav_bar/cupertino_sliver_nav_bar.1.dart} /// - // TODO(framework): End of the @dartpad directive. + /// const CupertinoSliverNavigationBar.search({ super.key, required Widget this.searchField, diff --git a/packages/cupertino_ui/lib/src/page_scaffold.dart b/packages/cupertino_ui/lib/src/page_scaffold.dart index 0c844fb5dbd4..dec3941a812b 100644 --- a/packages/cupertino_ui/lib/src/page_scaffold.dart +++ b/packages/cupertino_ui/lib/src/page_scaffold.dart @@ -25,16 +25,19 @@ import 'theme.dart'; /// encloses the [ScrollView]. The [ScrollView.primary] flag is used to connect /// a [ScrollView] to the enclosing [PrimaryScrollController]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [CupertinoPageScaffold] with a [Center] as a [child]. /// The [CupertinoButton] is connected to a callback that increments a counter. /// The [backgroundColor] can be changed. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/page_scaffold/cupertino_page_scaffold.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/picker.dart b/packages/cupertino_ui/lib/src/picker.dart index 2baccf0f3e38..54d9745958a9 100644 --- a/packages/cupertino_ui/lib/src/picker.dart +++ b/packages/cupertino_ui/lib/src/picker.dart @@ -50,15 +50,18 @@ const Curve _kCupertinoPickerTapToScrollCurve = Curves.easeInOut; /// /// By default, descendent texts are shown with [CupertinoTextThemeData.pickerTextStyle]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [CupertinoPicker] that displays a list of fruits on a wheel for /// selection. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/picker/cupertino_picker.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/radio.dart b/packages/cupertino_ui/lib/src/radio.dart index fc4cc59b9685..904edacd86b4 100644 --- a/packages/cupertino_ui/lib/src/radio.dart +++ b/packages/cupertino_ui/lib/src/radio.dart @@ -70,8 +70,7 @@ const List _kDisabledDarkGradientOpacities = [0.08, 0.14]; /// [RadioGroup.groupValue], and the [CupertinoRadio] under it with matching /// [value] will be selected. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Here is an example of CupertinoRadio widgets wrapped in CupertinoListTiles. /// @@ -85,9 +84,13 @@ const List _kDisabledDarkGradientOpacities = [0.08, 0.14]; /// This causes the buttons to rebuild with the updated `RadioGroup.groupValue`, and /// therefore the selection of the second button. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/radio/cupertino_radio.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -177,15 +180,18 @@ class CupertinoRadio extends StatefulWidget { /// {@macro flutter.widget.RawRadio.toggleable} /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows how to enable deselecting a radio button by setting the /// [toggleable] attribute. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro cupertino_ui.dartpad_guide} + /// /// {@example /example/lib/radio/cupertino_radio.toggleable.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final bool toggleable; /// Controls whether the radio displays in a checkbox style or the default iOS diff --git a/packages/cupertino_ui/lib/src/refresh.dart b/packages/cupertino_ui/lib/src/refresh.dart index e046f0687211..de8adb3e56d7 100644 --- a/packages/cupertino_ui/lib/src/refresh.dart +++ b/packages/cupertino_ui/lib/src/refresh.dart @@ -266,16 +266,19 @@ typedef RefreshCallback = Future Function(); /// sliver such as [CupertinoSliverNavigationBar] and your main scrollable /// content's sliver. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// When the user scrolls past [refreshTriggerPullDistance], /// this sample shows the default iOS pull to refresh indicator for 1 second and /// adds a new item to the top of the list view. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/refresh/cupertino_sliver_refresh_control.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/route.dart b/packages/cupertino_ui/lib/src/route.dart index 0baf10285d03..b289b55e7610 100644 --- a/packages/cupertino_ui/lib/src/route.dart +++ b/packages/cupertino_ui/lib/src/route.dart @@ -1294,8 +1294,7 @@ class CupertinoModalPopupRoute extends PopupRoute { /// /// For more information about state restoration, see [RestorationManager]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample demonstrates how to create a restorable Cupertino modal route. /// This is accomplished by enabling state restoration by specifying @@ -1304,9 +1303,13 @@ class CupertinoModalPopupRoute extends PopupRoute { /// /// {@macro flutter.widgets.RestorationManager} /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/route/show_cupertino_modal_popup.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -1390,8 +1393,7 @@ Widget _buildCupertinoDialogTransitions( /// /// For more information about state restoration, see [RestorationManager]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample demonstrates how to create a restorable Cupertino dialog. This is /// accomplished by enabling state restoration by specifying @@ -1400,9 +1402,13 @@ Widget _buildCupertinoDialogTransitions( /// /// {@macro flutter.widgets.RestorationManager} /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/route/show_cupertino_dialog.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/scrollbar.dart b/packages/cupertino_ui/lib/src/scrollbar.dart index 4f08927be983..d67531bdf2f5 100644 --- a/packages/cupertino_ui/lib/src/scrollbar.dart +++ b/packages/cupertino_ui/lib/src/scrollbar.dart @@ -43,8 +43,7 @@ const double _kScrollbarCrossAxisMargin = 3.0; /// animate from [thickness] and [radius] to [thicknessWhileDragging] and /// [radiusWhileDragging], respectively. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows a [CupertinoScrollbar] that fades in and out of view as scrolling occurs. /// The scrollbar will fade into view as the user scrolls, and fade out when scrolling stops. @@ -52,20 +51,27 @@ const double _kScrollbarCrossAxisMargin = 3.0; /// when it is dragged by the user. The `radius` of the scrollbar thumb corners will animate from 34 /// to the `radiusWhileDragging` of 0 when the scrollbar is being dragged by the user. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/scrollbar/cupertino_scrollbar.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// When [thumbVisibility] is true, the scrollbar thumb will remain visible without the /// fade animation. This requires that a [ScrollController] is provided to controller, /// or that the [PrimaryScrollController] is available. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/scrollbar/cupertino_scrollbar.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/search_field.dart b/packages/cupertino_ui/lib/src/search_field.dart index 7216749f4c6d..1a1e6d0a3ffd 100644 --- a/packages/cupertino_ui/lib/src/search_field.dart +++ b/packages/cupertino_ui/lib/src/search_field.dart @@ -38,29 +38,35 @@ const double _kMaxPrefixIconSize = 30.0; /// [controller]. For example, to set the initial value of the text field, use /// a [controller] that already contains some text such as: /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This examples shows how to provide initial text to a [CupertinoSearchTextField] /// using the [controller] property. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/search_field/cupertino_search_field.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// It is recommended to pass a [ValueChanged] to both [onChanged] and /// [onSubmitted] parameters in order to be notified once the value of the /// field changes or is submitted by the keyboard: /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This examples shows how to be notified of field changes or submitted text from /// a [CupertinoSearchTextField]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/search_field/cupertino_search_field.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/segmented_control.dart b/packages/cupertino_ui/lib/src/segmented_control.dart index d527f930f2b7..2b0044f13fb6 100644 --- a/packages/cupertino_ui/lib/src/segmented_control.dart +++ b/packages/cupertino_ui/lib/src/segmented_control.dart @@ -70,8 +70,7 @@ const Duration _kFadeDuration = Duration(milliseconds: 165); /// [disabledChildren]. If the child is not present in the [Set], it is enabled /// by default. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [CupertinoSegmentedControl] with an enum type. /// @@ -82,9 +81,13 @@ const Duration _kFadeDuration = Duration(milliseconds: 165); /// This example also demonstrates how to use the [disabledChildren] property by /// toggling each [CupertinoSwitch] to enable or disable the segments. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/segmented_control/cupertino_segmented_control.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/sheet.dart b/packages/cupertino_ui/lib/src/sheet.dart index 9f2bedb650d5..ceb88e1eeb5e 100644 --- a/packages/cupertino_ui/lib/src/sheet.dart +++ b/packages/cupertino_ui/lib/src/sheet.dart @@ -158,15 +158,18 @@ typedef _GetSheetDragged = bool Function(); /// Returns a [Future] that resolves to the value (if any) that was passed to /// [Navigator.pop] when the sheet was closed. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to navigate to use [showCupertinoSheet] to display a /// Cupertino sheet widget with nested navigation. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/sheet/cupertino_sheet.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -611,34 +614,43 @@ class _StretchDragControllerProvider extends InheritedWidget { /// scrollable area within the sheet, this parameter can be ignored. See below /// for an example. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to navigate to [CupertinoSheetRoute] by using it the /// same as a regular route. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/sheet/cupertino_sheet.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to show a Cupertino Sheet with nested navigation manually /// set up in order to enable restorable state. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/sheet/cupertino_sheet.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to show a Cupertino Sheet with scrollable content. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/sheet/cupertino_sheet.3.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// * [showCupertinoSheet], which is a convenience method for pushing a @@ -679,14 +691,17 @@ class CupertinoSheetRoute extends PageRoute with _CupertinoSheetRouteTrans /// then when a downward drag is applied to the scrollable area while the content /// is scrolled to the top, the drag to dismiss behavior of the sheet will be triggered. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows how to show a Cupertino Sheet with scrollable content. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro cupertino_ui.dartpad_guide} + /// /// {@example /example/lib/sheet/cupertino_sheet.3.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final ScrollableWidgetBuilder? scrollableBuilder; ScrollableWidgetBuilder get _effectiveBuilder { diff --git a/packages/cupertino_ui/lib/src/slider.dart b/packages/cupertino_ui/lib/src/slider.dart index 33047c757022..bad6ba52e2bd 100644 --- a/packages/cupertino_ui/lib/src/slider.dart +++ b/packages/cupertino_ui/lib/src/slider.dart @@ -52,14 +52,17 @@ const double _kVelocityThreshold = 1.0; /// that use a slider will listen for the [onChanged] callback and rebuild the /// slider with a new [value] to update the visual appearance of the slider. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to show the current slider value as it changes. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/slider/cupertino_slider.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/sliding_segmented_control.dart b/packages/cupertino_ui/lib/src/sliding_segmented_control.dart index d06ac15a3408..11ec7e0e0376 100644 --- a/packages/cupertino_ui/lib/src/sliding_segmented_control.dart +++ b/packages/cupertino_ui/lib/src/sliding_segmented_control.dart @@ -340,8 +340,7 @@ class _SegmentSeparatorState extends State<_SegmentSeparator> /// [thumbColor], [backgroundColor] arguments can be used to override the /// segmented control's colors from its defaults. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [CupertinoSlidingSegmentedControl] with an enum type. /// @@ -349,9 +348,14 @@ class _SegmentSeparatorState extends State<_SegmentSeparator> /// the parent [StatefulWidget] using the [State.setState] method, so that /// the parent gets rebuilt; for example: /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/segmented_control/cupertino_sliding_segmented_control.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// +/// /// See also: /// /// * @@ -508,16 +512,19 @@ class CupertinoSlidingSegmentedControl extends StatefulWidget /// /// Defaults to false. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows a [CupertinoSlidingSegmentedControl] with [isMomentary] set /// to true, providing feedback to the user when the segment is selected with a /// text scaling effect. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro cupertino_ui.dartpad_guide} + /// /// {@example /example/lib/segmented_control/cupertino_sliding_segmented_control.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final bool isMomentary; @override diff --git a/packages/cupertino_ui/lib/src/switch.dart b/packages/cupertino_ui/lib/src/switch.dart index 4db1901d3222..edb72459a99d 100644 --- a/packages/cupertino_ui/lib/src/switch.dart +++ b/packages/cupertino_ui/lib/src/switch.dart @@ -77,15 +77,18 @@ const CupertinoDynamicColor _kOffLabelColor = CupertinoDynamicColor.withBrightne /// callback and rebuild the switch with a new [value] to update the visual /// appearance of the switch. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a toggleable [CupertinoSwitch]. When the thumb slides to /// the other side of the track, the switch is toggled between on/off. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/switch/cupertino_switch.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// // TODO(framework): Replace the following block with a blue example container // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 diff --git a/packages/cupertino_ui/lib/src/tab_scaffold.dart b/packages/cupertino_ui/lib/src/tab_scaffold.dart index 55ca8e30cc30..81bee2042e74 100644 --- a/packages/cupertino_ui/lib/src/tab_scaffold.dart +++ b/packages/cupertino_ui/lib/src/tab_scaffold.dart @@ -22,15 +22,18 @@ import 'theme.dart'; /// [CupertinoTabController] controls, as well as the currently selected tab item of /// its [CupertinoTabBar]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This samples shows how [CupertinoTabController] can be used to switch tabs in /// [CupertinoTabScaffold]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/tab_scaffold/cupertino_tab_controller.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -108,14 +111,17 @@ class CupertinoTabController extends ChangeNotifier { /// (via [State.setState], for instance) from its descendant rather than from /// its ancestor. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// A sample code implementing a typical iOS information architecture with tabs. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/tab_scaffold/cupertino_tab_scaffold.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// To push a route above all tabs instead of inside the currently selected one /// (such as when showing a dialog on top of this scaffold), use diff --git a/packages/cupertino_ui/lib/src/text_field.dart b/packages/cupertino_ui/lib/src/text_field.dart index 32612565d1f3..12f116c8562e 100644 --- a/packages/cupertino_ui/lib/src/text_field.dart +++ b/packages/cupertino_ui/lib/src/text_field.dart @@ -147,15 +147,18 @@ class _CupertinoTextFieldSelectionGestureDetectorBuilder /// /// {@macro flutter.widgets.EditableText.onChanged} /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to set the initial value of the [CupertinoTextField] using /// a [controller] that already contains some text. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/text_field/cupertino_text_field.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// The [controller] can also control the selection and composing region (and to /// observe changes to the text, selection, and composing region). diff --git a/packages/cupertino_ui/lib/src/text_form_field_row.dart b/packages/cupertino_ui/lib/src/text_form_field_row.dart index 9de408b852a2..a0519a476180 100644 --- a/packages/cupertino_ui/lib/src/text_form_field_row.dart +++ b/packages/cupertino_ui/lib/src/text_form_field_row.dart @@ -78,15 +78,18 @@ import 'text_field.dart'; /// // TODO(framework): End of the blue example container. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to move the focus to the next field when the user /// presses the SPACE key. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro cupertino_ui.dartpad_guide} +/// /// {@example /example/lib/text_form_field_row/cupertino_text_form_field_row.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// class CupertinoTextFormFieldRow extends FormField { /// Creates a [CupertinoFormRow] containing a [FormField] that wraps /// a [CupertinoTextField]. diff --git a/packages/material_ui/analysis_options.yaml b/packages/material_ui/analysis_options.yaml index bd2a1b96a3d9..3e17bba73b77 100644 --- a/packages/material_ui/analysis_options.yaml +++ b/packages/material_ui/analysis_options.yaml @@ -13,3 +13,8 @@ analyzer: - windows/** - macos/** - linux/** + +linter: + rules: + # TODO(dkwingsmt): Remove when https://github.com/dart-lang/sdk/issues/63777 is fixed. + unintended_html_in_doc_comment: false diff --git a/packages/material_ui/lib/src/about.dart b/packages/material_ui/lib/src/about.dart index aa93f685e28d..00e5f9ce7aee 100644 --- a/packages/material_ui/lib/src/about.dart +++ b/packages/material_ui/lib/src/about.dart @@ -51,15 +51,18 @@ import 'theme.dart'; /// If your application does not have a [Drawer], you should provide an /// affordance to call [showAboutDialog] or (at least) [showLicensePage]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows two ways to open [AboutDialog]. The first one /// uses an [AboutListTile], and the second uses the [showAboutDialog] function. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/about/about_list_tile.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// class AboutListTile extends StatelessWidget { /// Creates a list tile for showing an about box. /// diff --git a/packages/material_ui/lib/src/action_chip.dart b/packages/material_ui/lib/src/action_chip.dart index ad5549771c39..ccee67d47e4f 100644 --- a/packages/material_ui/lib/src/action_chip.dart +++ b/packages/material_ui/lib/src/action_chip.dart @@ -45,15 +45,18 @@ enum _ChipVariant { flat, elevated } /// /// Requires one of its ancestors to be a [Material] widget. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to create an [ActionChip] with a leading icon. /// The icon is updated when the [ActionChip] is pressed. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/action_chip/action_chip.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Material Design 3 /// diff --git a/packages/material_ui/lib/src/action_icons_theme.dart b/packages/material_ui/lib/src/action_icons_theme.dart index a08374252afb..0289c7f414a6 100644 --- a/packages/material_ui/lib/src/action_icons_theme.dart +++ b/packages/material_ui/lib/src/action_icons_theme.dart @@ -146,15 +146,18 @@ class ActionIconThemeData with Diagnosticable { /// [CloseButtonIcon], [DrawerButtonIcon], and [EndDrawerButtonIcon] in this /// widget's subtree. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to define custom builders for drawer and back /// buttons. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/action_buttons/action_icon_theme.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// class ActionIconTheme extends InheritedTheme { /// Creates a theme that overrides the default icon of [BackButtonIcon], /// [CloseButtonIcon], [DrawerButtonIcon], and [EndDrawerButtonIcon] in this diff --git a/packages/material_ui/lib/src/adaptive_text_selection_toolbar.dart b/packages/material_ui/lib/src/adaptive_text_selection_toolbar.dart index b4a5651b1755..3563a0e85618 100644 --- a/packages/material_ui/lib/src/adaptive_text_selection_toolbar.dart +++ b/packages/material_ui/lib/src/adaptive_text_selection_toolbar.dart @@ -239,15 +239,18 @@ class AdaptiveTextSelectionToolbar extends StatelessWidget { /// button appearance for the given platform, but where the toolbar and/or the /// button actions and labels may be custom. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample demonstrates how to use `getAdaptiveButtons` to generate /// default button widgets in a custom toolbar. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/context_menu/editable_text_toolbar_builder.2.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// See also: /// diff --git a/packages/material_ui/lib/src/animated_icons/animated_icons.dart b/packages/material_ui/lib/src/animated_icons/animated_icons.dart index e544da1d9cb6..4ae2859f6178 100644 --- a/packages/material_ui/lib/src/animated_icons/animated_icons.dart +++ b/packages/material_ui/lib/src/animated_icons/animated_icons.dart @@ -16,15 +16,18 @@ part of material_animated_icons; // ignore: use_string_in_part_of_directives /// /// {@youtube 560 315 https://www.youtube.com/watch?v=pJcbh8pbvJs} /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to create an animated icon. The icon is animated /// forward and reverse in a loop. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/animated_icon/animated_icon.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/animated_icons/animated_icons_data.dart b/packages/material_ui/lib/src/animated_icons/animated_icons_data.dart index 889618532f5a..392c725e2fae 100644 --- a/packages/material_ui/lib/src/animated_icons/animated_icons_data.dart +++ b/packages/material_ui/lib/src/animated_icons/animated_icons_data.dart @@ -14,15 +14,18 @@ part of material_animated_icons; // ignore: use_string_in_part_of_directives /// /// Use with [AnimatedIcon] class to show specific animated icons. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to create an animated icon. The icon is animated /// forward and reverse in a loop. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/animated_icon/animated_icons_data.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/app.dart b/packages/material_ui/lib/src/app.dart index fdfef4617901..8e5c830a7bdd 100644 --- a/packages/material_ui/lib/src/app.dart +++ b/packages/material_ui/lib/src/app.dart @@ -816,15 +816,24 @@ class MaterialApp extends StatefulWidget { /// /// To disable the theme animation, use [AnimationStyle.noAnimation]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample showcases how to override the theme animation curve and /// duration in the [MaterialApp] widget using [AnimationStyle]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@template material_ui.dartpad_guide} + /// + /// + /// To see it in action, copy and run this code snippet on [DartPad](https://dartpad.dev/). + /// + /// + /// {@endtemplate} + /// /// {@example /example/lib/app/app.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final AnimationStyle? themeAnimationStyle; @override diff --git a/packages/material_ui/lib/src/app_bar.dart b/packages/material_ui/lib/src/app_bar.dart index 569451926577..236fac16113d 100644 --- a/packages/material_ui/lib/src/app_bar.dart +++ b/packages/material_ui/lib/src/app_bar.dart @@ -123,27 +123,34 @@ class _PreferredAppBarSize extends Size { /// to suddenly jump. Wrap the [AppBar] in a [MediaQuery] widget, and adjust its /// padding such that the animation is smooth. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows an [AppBar] with two simple actions. The first action /// opens a [SnackBar], while the second action navigates to a new page. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/app_bar/app_bar.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// Material Design 3 introduced new types of app bar. -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// +/// /// /// This sample shows the creation of an [AppBar] widget with the [shadowColor] and /// [scrolledUnderElevation] properties set, as described in: /// https://m3.material.io/components/top-app-bar/overview /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/app_bar/app_bar.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Troubleshooting /// @@ -163,26 +170,32 @@ class _PreferredAppBarSize extends Size { /// [ColorScheme.primary]. To remedy the problem, override /// [TextButton.style]: /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows an [AppBar] with two action buttons with their primary /// color set to [ColorScheme.onPrimary]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/app_bar/app_bar.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to listen to a nested Scrollable's scroll notification /// in a nested scroll view using the [notificationPredicate] property and use it /// to make [scrolledUnderElevation] take effect. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/app_bar/app_bar.3.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -528,15 +541,18 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget { /// zero. /// {@endtemplate} /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample demonstrates how to implement a custom app bar shape for the /// [shape] property. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/app_bar/app_bar.4.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// See also: /// @@ -1542,25 +1558,30 @@ class _SliverAppBarDelegate extends SliverPersistentHeaderDelegate { /// // TODO(framework): End of the blue example container. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Here is an example of [SliverAppBar] when using [stretch] and [onStretchTrigger]. /// -/// {@example /example/lib/app_bar/sliver_app_bar.4.dart} +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} /// -// TODO(framework): End of the @dartpad directive. +/// {@example /example/lib/app_bar/sliver_app_bar.4.dart} /// +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows a [SliverAppBar] and its behavior when using the /// [pinned], [snap] and [floating] parameters. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/app_bar/sliver_app_bar.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Animated Examples /// @@ -1660,14 +1681,17 @@ class SliverAppBar extends StatefulWidget { /// title will fade in on the main row. The reverse will happen if it is /// expanded again. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample shows how to use [SliverAppBar.medium] in a [CustomScrollView]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/app_bar/sliver_app_bar.2.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// See also: /// @@ -1734,14 +1758,17 @@ class SliverAppBar extends StatefulWidget { /// title will fade in on the main row. The reverse will happen if it is /// expanded again. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample shows how to use [SliverAppBar.large] in a [CustomScrollView]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/app_bar/sliver_app_bar.3.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// See also: /// diff --git a/packages/material_ui/lib/src/autocomplete.dart b/packages/material_ui/lib/src/autocomplete.dart index 627049497815..9f7a762ebd18 100644 --- a/packages/material_ui/lib/src/autocomplete.dart +++ b/packages/material_ui/lib/src/autocomplete.dart @@ -14,58 +14,73 @@ import 'theme.dart'; /// /// {@youtube 560 315 https://www.youtube.com/watch?v=-Nny8kzW380} /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to create a very basic Autocomplete widget using the /// default UI. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/autocomplete/autocomplete.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to create an Autocomplete widget with a custom type. /// Try searching with text from the name or email field. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/autocomplete/autocomplete.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to create an Autocomplete widget whose options are /// fetched over the network. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/autocomplete/autocomplete.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to create an Autocomplete widget whose options are /// fetched over the network. It uses debouncing to wait to perform the network /// request until after the user finishes typing. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/autocomplete/autocomplete.3.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to create an Autocomplete widget whose options are /// fetched over the network. It includes both debouncing and error handling, so /// that failed network requests show an error to the user and can be recovered /// from. Try toggling the network Switch widget to simulate going offline. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/autocomplete/autocomplete.4.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/badge.dart b/packages/material_ui/lib/src/badge.dart index 43dd3950484e..f9e213263612 100644 --- a/packages/material_ui/lib/src/badge.dart +++ b/packages/material_ui/lib/src/badge.dart @@ -31,15 +31,18 @@ import 'theme.dart'; /// configuration is intended to work well with a default sized (24) /// [Icon]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to create a [Badge] with label and count /// wrapped on an icon in an [IconButton]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/badge/badge.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// class Badge extends StatelessWidget { /// Create a Badge that stacks [label] on top of [child]. /// diff --git a/packages/material_ui/lib/src/banner.dart b/packages/material_ui/lib/src/banner.dart index f64704937197..6fe349285cf1 100644 --- a/packages/material_ui/lib/src/banner.dart +++ b/packages/material_ui/lib/src/banner.dart @@ -71,24 +71,30 @@ enum MaterialBannerClosedReason { /// They are persistent and non-modal, allowing the user to either ignore them or /// interact with them at any time. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Banners placed directly into the widget tree are static. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/banner/material_banner.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// MaterialBanner's can also be presented through a [ScaffoldMessenger]. /// Here is an example where ScaffoldMessengerState.showMaterialBanner() is used to show the MaterialBanner. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/banner/material_banner.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// The [actions] will be placed beside the [content] if there is only one. /// Otherwise, the [actions] will be placed below the [content]. Use diff --git a/packages/material_ui/lib/src/bottom_app_bar.dart b/packages/material_ui/lib/src/bottom_app_bar.dart index 41849b89592f..5fe9912bc1bd 100644 --- a/packages/material_ui/lib/src/bottom_app_bar.dart +++ b/packages/material_ui/lib/src/bottom_app_bar.dart @@ -44,28 +44,34 @@ import 'theme.dart'; /// // TODO(framework): End of the blue example container. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows the [BottomAppBar], which can be configured to have a notch using the /// [BottomAppBar.shape] property. This also includes an optional [FloatingActionButton], which illustrates /// the [FloatingActionButtonLocation]s in relation to the [BottomAppBar]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/bottom_app_bar/bottom_app_bar.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows Material 3 [BottomAppBar] with its expected look and behaviors. /// /// This also includes an optional [FloatingActionButton], which illustrates /// the [FloatingActionButtonLocation.endContained]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/bottom_app_bar/bottom_app_bar.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/bottom_navigation_bar.dart b/packages/material_ui/lib/src/bottom_navigation_bar.dart index 710b1eedd1a7..3aff99c6bbbb 100644 --- a/packages/material_ui/lib/src/bottom_navigation_bar.dart +++ b/packages/material_ui/lib/src/bottom_navigation_bar.dart @@ -134,8 +134,7 @@ enum BottomNavigationBarLandscapeLayout { /// /// ## Using [BottomNavigationBar] /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [BottomNavigationBar] as it is used within a [Scaffold] /// widget. The [BottomNavigationBar] has three [BottomNavigationBarItem] @@ -144,22 +143,28 @@ enum BottomNavigationBarLandscapeLayout { /// amber. The `_onItemTapped` function changes the selected item's index /// and displays a corresponding message in the center of the [Scaffold]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/bottom_navigation_bar/bottom_navigation_bar.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how you would migrate the above [BottomNavigationBar] /// to the new [NavigationBar]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/navigation_bar/navigation_bar.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [BottomNavigationBar] as it is used within a [Scaffold] /// widget. The [BottomNavigationBar] has four [BottomNavigationBarItem] @@ -171,21 +176,29 @@ enum BottomNavigationBarLandscapeLayout { /// selected item's index and displays a corresponding message in the center of /// the [Scaffold]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/bottom_navigation_bar/bottom_navigation_bar.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows [BottomNavigationBar] used in a [Scaffold] Widget with /// different interaction patterns. Tapping twice on the first [BottomNavigationBarItem] /// uses the [ScrollController] to animate the [ListView] to the top. The second /// [BottomNavigationBarItem] shows a Modal Dialog. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/bottom_navigation_bar/bottom_navigation_bar.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// +/// /// See also: /// /// * [BottomNavigationBarItem] diff --git a/packages/material_ui/lib/src/bottom_sheet.dart b/packages/material_ui/lib/src/bottom_sheet.dart index e9c9180c7d8c..2865eb0560ba 100644 --- a/packages/material_ui/lib/src/bottom_sheet.dart +++ b/packages/material_ui/lib/src/bottom_sheet.dart @@ -1228,27 +1228,33 @@ class ModalBottomSheetRoute extends PopupRoute { /// Will default to [MaterialLocalizations.modalBarrierDismissLabel] of context /// if not set. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example demonstrates how to use [showModalBottomSheet] to display a /// bottom sheet that obscures the content behind it when a user taps a button. /// It also demonstrates how to close the bottom sheet using the [Navigator] /// when a user taps on a button inside the bottom sheet. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/bottom_sheet/show_modal_bottom_sheet.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows the creation of [showModalBottomSheet], as described in: /// https://m3.material.io/components/bottom-sheets/overview /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/bottom_sheet/show_modal_bottom_sheet.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// The [sheetAnimationStyle] parameter is used to override the modal bottom sheet /// animation duration and reverse animation duration. @@ -1267,15 +1273,18 @@ class ModalBottomSheetRoute extends PopupRoute { /// /// To disable the bottom sheet animation, use [AnimationStyle.noAnimation]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample showcases how to override the [showModalBottomSheet] animation /// duration and reverse animation duration using [AnimationStyle]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/bottom_sheet/show_modal_bottom_sheet.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -1374,15 +1383,18 @@ Future showModalBottomSheet({ /// /// To disable the bottom sheet animation, use [AnimationStyle.noAnimation]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample showcases how to override the [showBottomSheet] animation /// duration and reverse animation duration using [AnimationStyle]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/bottom_sheet/show_bottom_sheet.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// To rebuild the bottom sheet (e.g. if it is stateful), call /// [PersistentBottomSheetController.setState] on the controller returned by diff --git a/packages/material_ui/lib/src/button_style.dart b/packages/material_ui/lib/src/button_style.dart index 673bbf2dc85b..71a295af3df4 100644 --- a/packages/material_ui/lib/src/button_style.dart +++ b/packages/material_ui/lib/src/button_style.dart @@ -146,14 +146,17 @@ typedef ButtonLayerBuilder = /// | Outlined | [OutlinedButton] | /// | Text | [TextButton] | /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to create each of the Material 3 button types with Flutter. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/button_style/button_style.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/button_style_button.dart b/packages/material_ui/lib/src/button_style_button.dart index 65e12b9b9378..41f833ea8af7 100644 --- a/packages/material_ui/lib/src/button_style_button.dart +++ b/packages/material_ui/lib/src/button_style_button.dart @@ -44,15 +44,18 @@ import 'tooltip.dart'; /// /// Defaults to [IconAlignment.start]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample demonstrates how to use `iconAlignment` to align the button icon to the start /// or the end of the button. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/icon_alignment/icon_alignment.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// {@endtemplate} enum IconAlignment { diff --git a/packages/material_ui/lib/src/card.dart b/packages/material_ui/lib/src/card.dart index 09ebec9b9ca1..80f93f98a741 100644 --- a/packages/material_ui/lib/src/card.dart +++ b/packages/material_ui/lib/src/card.dart @@ -29,29 +29,35 @@ enum _CardVariant { elevated, filled, outlined } /// some text describing a musical, and the other with buttons for buying /// tickets or listening to the show.](https://flutter.github.io/assets-for-api-docs/assets/material/card.png) /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows creation of a [Card] widget that shows album information /// and two actions. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/card/card.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// Sometimes the primary action area of a card is the card itself. Cards can be /// one large touch target that shows a detail screen when tapped. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows creation of a [Card] widget that can be tapped. When /// tapped this [Card]'s [InkWell] displays an "ink splash" that fills the /// entire card. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/card/card.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// For Material Design 2 (when [ThemeData.useMaterial3] is false), there is a /// single card type: the elevated card. In that mode the named constructors @@ -63,15 +69,18 @@ enum _CardVariant { elevated, filled, outlined } /// so theme properties (for example [CardThemeData.shape]) apply to every card /// variant within the theme's scope. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows creation of [Card] widgets for elevated, filled and /// outlined types, as described in: https://m3.material.io/components/cards/overview /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/card/card.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/carousel.dart b/packages/material_ui/lib/src/carousel.dart index 7ef95af25ef5..7b7a253c7c40 100644 --- a/packages/material_ui/lib/src/carousel.dart +++ b/packages/material_ui/lib/src/carousel.dart @@ -112,8 +112,7 @@ import 'theme.dart'; /// visible items may be slightly compressed during scrolling. The [shrinkExtent] /// property controls the minimum allowable size for these compressed items. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Here is an example to show different carousel layouts that [CarouselView] /// and [CarouselView.weighted] can build. @@ -127,9 +126,13 @@ import 'theme.dart'; /// This key-driven behavior is dictated by the [ScrollBehavior.pointerAxisModifiers], /// while [ScrollBehavior.dragDevices] manages what devices can drag a scrollable. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/carousel/carousel.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -236,14 +239,17 @@ class CarouselView extends StatefulWidget { /// The [itemBuilder] callback will be called only with indices greater than /// or equal to zero and less than [itemCount]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows how to create a carousel with 1000 items using lazy loading: /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/carousel/carousel.1.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// See also: /// diff --git a/packages/material_ui/lib/src/checkbox.dart b/packages/material_ui/lib/src/checkbox.dart index 1a6e53f4dbd6..d9b8e03e992f 100644 --- a/packages/material_ui/lib/src/checkbox.dart +++ b/packages/material_ui/lib/src/checkbox.dart @@ -40,8 +40,7 @@ enum _CheckboxType { material, adaptive } /// /// Requires one of its ancestors to be a [Material] widget. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how you can override the default theme of /// a [Checkbox] with a [WidgetStateProperty]. @@ -49,18 +48,25 @@ enum _CheckboxType { material, adaptive } /// is being pressed, hovered, or focused. Otherwise, the checkbox's color will /// be `Colors.red`. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/checkbox/checkbox.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows what the checkbox error state looks like. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/checkbox/checkbox.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/checkbox_list_tile.dart b/packages/material_ui/lib/src/checkbox_list_tile.dart index 5bf87f9e0670..15b815fad646 100644 --- a/packages/material_ui/lib/src/checkbox_list_tile.dart +++ b/packages/material_ui/lib/src/checkbox_list_tile.dart @@ -91,8 +91,7 @@ enum _CheckboxType { material, adaptive } /// To show the [CheckboxListTile] as disabled, pass null as the [onChanged] /// callback. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// ![CheckboxListTile sample](https://flutter.github.io/assets-for-api-docs/assets/material/checkbox_list_tile.png) /// @@ -102,19 +101,26 @@ enum _CheckboxType { material, adaptive } /// This sample requires that you also import 'package:flutter/scheduler.dart', /// so that you can reference [timeDilation]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/checkbox_list_tile/checkbox_list_tile.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample demonstrates how [CheckboxListTile] positions the checkbox widget /// relative to the text in different configurations. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/checkbox_list_tile/checkbox_list_tile.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Semantics in CheckboxListTile /// @@ -133,8 +139,7 @@ enum _CheckboxType { material, adaptive } /// into one. Therefore, it may be necessary to create a custom radio tile /// widget to accommodate similar use cases. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// ![Checkbox list tile semantics sample](https://flutter.github.io/assets-for-api-docs/assets/material/checkbox_list_tile_semantics.png) /// @@ -142,9 +147,13 @@ enum _CheckboxType { material, adaptive } /// LinkedLabelCheckbox, that includes an interactive [RichText] widget that /// handles tap gestures. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/checkbox_list_tile/custom_labeled_checkbox.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## CheckboxListTile isn't exactly what I want /// @@ -153,17 +162,20 @@ enum _CheckboxType { material, adaptive } /// combining [Checkbox] with other widgets, such as [Text], [Padding] and /// [InkWell]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// ![Custom checkbox list tile sample](https://flutter.github.io/assets-for-api-docs/assets/material/checkbox_list_tile_custom.png) /// /// Here is an example of a custom LabeledCheckbox widget, but you can easily /// make your own configurable widget. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/checkbox_list_tile/custom_labeled_checkbox.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/chip.dart b/packages/material_ui/lib/src/chip.dart index 93601ea6735c..c32dead96c36 100644 --- a/packages/material_ui/lib/src/chip.dart +++ b/packages/material_ui/lib/src/chip.dart @@ -244,14 +244,17 @@ abstract interface class ChipAttributes { /// Specifying this parameter enables creation of avatar smaller than /// the minimum size, but it is not recommended. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample shows how to use [avatarBoxConstraints] to adjust avatar size constraints /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/chip/chip_attributes.avatar_box_constraints.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// BoxConstraints? get avatarBoxConstraints; /// Used to override the default chip animations durations. @@ -272,15 +275,18 @@ abstract interface class ChipAttributes { /// is provided, it will be used to override the chip delete icon animation duration. /// If it is null, then default duration will be 150ms. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample showcases how to override the chip animations durations using /// [ChipAnimationStyle]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/chip/chip_attributes.chip_animation_style.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// ChipAnimationStyle? get chipAnimationStyle; /// The cursor for a mouse pointer when it enters or is hovering over the @@ -334,15 +340,18 @@ abstract interface class DeletableChipAttributes { /// that the user tapped the delete button. In order to delete the chip, you /// have to do something similar to the following sample: /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample shows how to use [onDeleted] to remove an entry when the /// delete button is tapped. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/chip/deletable_chip_attributes.on_deleted.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// VoidCallback? get onDeleted; /// Used to define the delete icon's color with an [IconTheme] that @@ -376,15 +385,18 @@ abstract interface class DeletableChipAttributes { /// Specifying this parameter enables creation of delete icon smaller than /// the minimum size, but it is not recommended. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample shows how to use [deleteIconBoxConstraints] to adjust delete icon /// size constraints. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/chip/deletable_chip_attributes.delete_icon_box_constraints.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// BoxConstraints? get deleteIconBoxConstraints; } diff --git a/packages/material_ui/lib/src/choice_chip.dart b/packages/material_ui/lib/src/choice_chip.dart index 0e886f3ffacf..e820dc69d9ca 100644 --- a/packages/material_ui/lib/src/choice_chip.dart +++ b/packages/material_ui/lib/src/choice_chip.dart @@ -30,15 +30,18 @@ enum _ChipVariant { flat, elevated } /// /// Requires one of its ancestors to be a [Material] widget. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to create [ChoiceChip]s with [onSelected]. When the /// user taps, the chip will be selected. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/choice_chip/choice_chip.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Material Design 3 /// diff --git a/packages/material_ui/lib/src/color_scheme.dart b/packages/material_ui/lib/src/color_scheme.dart index e5d7d16920db..c8097bf3ce1d 100644 --- a/packages/material_ui/lib/src/color_scheme.dart +++ b/packages/material_ui/lib/src/color_scheme.dart @@ -114,15 +114,18 @@ enum DynamicSchemeVariant { /// with on '-Fixed' roles, such as [onPrimaryFixed], they provide a /// lower-emphasis option for text and icons. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows all Material [ColorScheme] roles in light and dark /// brightnesses. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/color_scheme/color_scheme.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ### Setting Colors in Flutter /// @@ -254,16 +257,19 @@ class ColorScheme with Diagnosticable { /// -1.0 is the lowest; 1.0 is the highest. From Material Design guideline, the /// medium and high contrast correspond to 0.5 and 1.0 respectively. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample shows how to use [ColorScheme.fromSeed] to create dynamic /// color schemes with different [DynamicSchemeVariant]s and different /// contrast level. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/color_scheme/color_scheme.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// See also: /// @@ -1723,15 +1729,18 @@ class ColorScheme with Diagnosticable { /// The provided image will be scaled down to a maximum size of 112x112 pixels /// during color extraction. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample shows how to use [ColorScheme.fromImageProvider] to create /// content-based dynamic color schemes. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/color_scheme/dynamic_content_color.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// See also: /// diff --git a/packages/material_ui/lib/src/data_table.dart b/packages/material_ui/lib/src/data_table.dart index 40a0e5b051e8..7109aea3180b 100644 --- a/packages/material_ui/lib/src/data_table.dart +++ b/packages/material_ui/lib/src/data_table.dart @@ -408,8 +408,7 @@ class DataCell { /// multiple pages. /// * [CustomScrollView], for greater control over scrolling effects. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to display a [DataTable] with three columns: name, age, and /// role. The columns are defined by three [DataColumn] objects. The table @@ -418,20 +417,27 @@ class DataCell { /// /// ![](https://flutter.github.io/assets-for-api-docs/assets/material/data_table.png) /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/data_table/data_table.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to display a [DataTable] with alternate colors per /// row, and a custom color for when the row is selected. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/data_table/data_table.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// [DataTable] can be sorted on the basis of any column in [columns] in /// ascending or descending order. If [sortColumnIndex] is non-null, then the diff --git a/packages/material_ui/lib/src/date.dart b/packages/material_ui/lib/src/date.dart index b621334c6c07..d18e882132c8 100644 --- a/packages/material_ui/lib/src/date.dart +++ b/packages/material_ui/lib/src/date.dart @@ -18,15 +18,18 @@ import 'material_localizations.dart'; /// navigated within the picker. Different calendar systems (e.g., Gregorian, /// Nepali, Hijri, Buddhist) can be supported by providing custom implementations. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example demonstrates how a [CalendarDelegate] is used to implement a /// custom calendar system in the date picker. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/date_picker/custom_calendar_date_picker.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/date_picker.dart b/packages/material_ui/lib/src/date_picker.dart index b74bf0a749a5..146abf4d4cc9 100644 --- a/packages/material_ui/lib/src/date_picker.dart +++ b/packages/material_ui/lib/src/date_picker.dart @@ -157,15 +157,18 @@ const double _fontSizeToScale = 14.0; /// /// {@macro flutter.widgets.RawDialogRoute} /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample demonstrates how to create a basic date picker. /// Tapping the button displays a date picker which returns the selected date. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/date_picker/show_date_picker.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ### State Restoration /// @@ -178,17 +181,20 @@ const double _fontSizeToScale = 14.0; /// /// {@macro flutter.widgets.RestorationManager} /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample demonstrates how to create a restorable Material date picker. /// This is accomplished by enabling state restoration by specifying /// [MaterialApp.restorationScopeId] and using [Navigator.restorablePush] to /// push [DatePickerDialog] when the button is tapped. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/date_picker/show_date_picker.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -1152,17 +1158,20 @@ typedef SelectableDayForRangePredicate = /// /// {@macro flutter.widgets.RestorationManager} /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample demonstrates how to create a restorable Material date range picker. /// This is accomplished by enabling state restoration by specifying /// [MaterialApp.restorationScopeId] and using [Navigator.restorablePush] to /// push [DateRangePickerDialog] when the button is tapped. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/date_picker/show_date_range_picker.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/date_picker_theme.dart b/packages/material_ui/lib/src/date_picker_theme.dart index 55a5036bce72..0314a1cef4ab 100644 --- a/packages/material_ui/lib/src/date_picker_theme.dart +++ b/packages/material_ui/lib/src/date_picker_theme.dart @@ -243,16 +243,19 @@ class DatePickerThemeData with Diagnosticable { /// value of [dayBackgroundColor] is used to paint the shape decoration of /// the day label. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample demonstrates how to customize the day selector shape decoration /// using the [dayShape], [todayForegroundColor], [todayBackgroundColor], and /// [todayBorder] properties. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/date_picker/date_picker_theme_day_shape.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final WidgetStateProperty? dayShape; /// Overrides the default color used to paint the @@ -262,16 +265,19 @@ class DatePickerThemeData with Diagnosticable { /// /// This will be used instead of the [TextStyle.color] provided in [dayStyle]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample demonstrates how to customize the day selector shape decoration /// using the [dayShape], [todayForegroundColor], [todayBackgroundColor], and /// [todayBorder] properties. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/date_picker/date_picker_theme_day_shape.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final WidgetStateProperty? todayForegroundColor; /// Overrides the default color used to paint the background of the @@ -287,16 +293,19 @@ class DatePickerThemeData with Diagnosticable { /// is used as specified. To omit the border entirely, /// set [todayBorder] to [BorderSide.none]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample demonstrates how to customize the day selector shape decoration /// using the [dayShape], [todayForegroundColor], [todayBackgroundColor], and /// [todayBorder] properties. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/date_picker/date_picker_theme_day_shape.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final BorderSide? todayBorder; /// Overrides the default text style used to paint each of the year diff --git a/packages/material_ui/lib/src/dialog.dart b/packages/material_ui/lib/src/dialog.dart index 9739a4efbb76..edf949ab0e17 100644 --- a/packages/material_ui/lib/src/dialog.dart +++ b/packages/material_ui/lib/src/dialog.dart @@ -38,14 +38,17 @@ const EdgeInsets _defaultInsetPadding = EdgeInsets.symmetric(horizontal: 40.0, v /// or [SimpleDialog], which implement specific kinds of Material Design /// dialogs. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows the creation of [Dialog] and [Dialog.fullscreen] widgets. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/dialog/dialog.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Contraints /// The Material 3 guideline recommends that a dialog should have a maximal width of 560dp. @@ -385,26 +388,32 @@ class Dialog extends StatelessWidget { /// // TODO(framework): End of the blue example container. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This demo shows a [TextButton] which when pressed, calls [showDialog]. When called, this method /// displays a Material dialog above the current contents of the app and returns /// a [Future] that completes when the dialog is dismissed. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/dialog/alert_dialog.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows the creation of [AlertDialog], as described in: /// https://m3.material.io/components/dialogs/overview /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/dialog/alert_dialog.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Alert dialogs and scrolling /// @@ -490,8 +499,7 @@ class AlertDialog extends StatelessWidget { /// /// The target platform is based on the current [Theme]: [ThemeData.platform]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This demo shows a [TextButton] which when pressed, calls [showAdaptiveDialog]. /// When called, this method displays an adaptive dialog above the current @@ -500,9 +508,13 @@ class AlertDialog extends StatelessWidget { /// [CupertinoDialogAction] is conditionally used as the child to show more /// platform specific design. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/dialog/adaptive_alert_dialog.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// const factory AlertDialog.adaptive({ Key? key, Widget? icon, @@ -1609,24 +1621,30 @@ class _DialogContentPage extends Page { /// Returns a [Future] that resolves to the value (if any) that was passed to /// [Navigator.pop] when the dialog was closed. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample demonstrates how to use [showDialog] to display a dialog box. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/dialog/show_dialog.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows the creation of [showDialog], as described in: /// https://m3.material.io/components/dialogs/overview /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/dialog/show_dialog.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ### State Restoration in Dialogs /// @@ -1636,8 +1654,7 @@ class _DialogContentPage extends Page { /// /// For more information about state restoration, see [RestorationManager]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample demonstrates how to create a restorable Material dialog. This is /// accomplished by enabling state restoration by specifying @@ -1646,9 +1663,13 @@ class _DialogContentPage extends Page { /// /// {@macro flutter.widgets.RestorationManager} /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/dialog/show_dialog.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/divider.dart b/packages/material_ui/lib/src/divider.dart index 214d06fee3f3..5b5fa614207c 100644 --- a/packages/material_ui/lib/src/divider.dart +++ b/packages/material_ui/lib/src/divider.dart @@ -29,8 +29,7 @@ import 'theme.dart'; /// The box's total height is controlled by [height]. The appropriate /// padding is automatically computed from the height. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to display a Divider between an orange and blue box /// inside a column. The Divider is 20 logical pixels in height and contains a @@ -39,19 +38,26 @@ import 'theme.dart'; /// /// ![](https://flutter.github.io/assets-for-api-docs/assets/material/divider.png) /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/divider/divider.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows the creation of [Divider] widget, as described in: /// https://m3.material.io/components/divider/overview /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/divider/divider.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -234,27 +240,33 @@ class Divider extends StatelessWidget { /// The box's total width is controlled by [width]. The appropriate /// padding is automatically computed from the width. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to display a [VerticalDivider] between a purple and orange box /// inside a [Row]. The [VerticalDivider] is 20 logical pixels in width and contains a /// horizontally centered black line that is 1 logical pixels thick. The grey /// line is indented by 20 logical pixels. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/divider/vertical_divider.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows the creation of [VerticalDivider] widget, as described in: /// https://m3.material.io/components/divider/overview /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/divider/vertical_divider.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/drawer.dart b/packages/material_ui/lib/src/drawer.dart index 2443856d51c3..a545c55fb1dc 100644 --- a/packages/material_ui/lib/src/drawer.dart +++ b/packages/material_ui/lib/src/drawer.dart @@ -96,8 +96,7 @@ const Duration _kBaseSettleDuration = Duration(milliseconds: 246); /// [NavigationDrawerDestination] widgets and/or customized widgets like headlines /// and dividers. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to create a [Scaffold] that contains an [AppBar] and /// a [Drawer]. A user taps the "menu" icon in the [AppBar] to open the @@ -105,18 +104,25 @@ const Duration _kBaseSettleDuration = Duration(milliseconds: 246); /// The [Drawer] displays the four items using a [ListView], which allows the /// user to scroll through the items if need be. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/drawer/drawer.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to migrate the above [Drawer] to a [NavigationDrawer]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/navigation_drawer/navigation_drawer.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// An open drawer may be closed with a swipe to close gesture, pressing the /// escape key, by tapping the scrim, or by calling pop route function such as diff --git a/packages/material_ui/lib/src/dropdown.dart b/packages/material_ui/lib/src/dropdown.dart index 026359cd11b8..352b29752613 100644 --- a/packages/material_ui/lib/src/dropdown.dart +++ b/packages/material_ui/lib/src/dropdown.dart @@ -939,8 +939,7 @@ class DropdownButtonHideUnderline extends InheritedWidget { /// dropdown with the new value. /// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows a [DropdownButton] with a large arrow icon, /// purple text style, and bold purple underline, whose value is one of "One", @@ -948,9 +947,13 @@ class DropdownButtonHideUnderline extends InheritedWidget { /// /// ![](https://flutter.github.io/assets-for-api-docs/assets/material/dropdown_button.png) /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/dropdown/dropdown_button.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// If the [onChanged] callback is null or the list of [items] is null /// then the dropdown button will be disabled, i.e. its arrow will be @@ -959,15 +962,18 @@ class DropdownButtonHideUnderline extends InheritedWidget { /// [disabledHint] is null and [hint] is non-null, the [hint] widget will /// instead be displayed. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how you would rewrite the above [DropdownButton] /// to use the [DropdownMenu]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/dropdown_menu/dropdown_menu.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// /// See also: @@ -1155,15 +1161,18 @@ class DropdownButton extends StatefulWidget { /// from the list corresponds to the [DropdownMenuItem] of the same index /// in [items]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample shows a `DropdownButton` with a button with [Text] that /// corresponds to but is unique from [DropdownMenuItem]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/dropdown/dropdown_button.selected_item_builder.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// If this callback is null, the [DropdownMenuItem] from [items] /// that matches [value] will be displayed. @@ -1186,15 +1195,18 @@ class DropdownButton extends StatefulWidget { /// To use a separate text style for selected item when it's displayed within /// the dropdown button, consider using [selectedItemBuilder]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample shows a `DropdownButton` with a dropdown button text style /// that is different than its menu items. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/dropdown/dropdown_button.style.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// Defaults to the [TextTheme.titleMedium] value of the current /// [ThemeData.textTheme] of the current [Theme]. diff --git a/packages/material_ui/lib/src/dropdown_menu.dart b/packages/material_ui/lib/src/dropdown_menu.dart index 662daab7db3c..1c62eba2ccc9 100644 --- a/packages/material_ui/lib/src/dropdown_menu.dart +++ b/packages/material_ui/lib/src/dropdown_menu.dart @@ -101,16 +101,19 @@ class DropdownMenuEntry { /// To control the text that appears in the text field for a selected item, /// set the [label] property to a descriptive string. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample shows how to override the default label [Text] /// widget with one that forces the menu entry to appear on one line /// by specifying [Text.maxLines] and [Text.overflow]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/dropdown_menu/dropdown_menu_entry_label_widget.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final Widget? labelWidget; /// An optional icon to display before the label. @@ -164,14 +167,17 @@ enum DropdownMenuCloseBehavior { /// /// The menu can be scrollable if not all items in the list are displayed at once. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to display outlined [DropdownMenu] and filled [DropdownMenu]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/dropdown_menu/dropdown_menu.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -248,15 +254,18 @@ class DropdownMenu extends StatefulWidget { /// /// Defaults to true. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample demonstrates how the [enabled] and [requestFocusOnTap] properties /// affect the textfield's hover cursor. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/dropdown_menu/dropdown_menu.2.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final bool enabled; /// Determine the width of the [DropdownMenu]. @@ -523,15 +532,18 @@ class DropdownMenu extends StatefulWidget { /// /// Set this to true or false explicitly to override the default behavior. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample demonstrates how the [enabled] and [requestFocusOnTap] properties /// affect the textfield's hover cursor. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/dropdown_menu/dropdown_menu.2.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final bool? requestFocusOnTap; /// Determines if the dropdown menu behaves as a 'select' component. diff --git a/packages/material_ui/lib/src/elevated_button.dart b/packages/material_ui/lib/src/elevated_button.dart index e06a9ba42ecc..dff74bff7455 100644 --- a/packages/material_ui/lib/src/elevated_button.dart +++ b/packages/material_ui/lib/src/elevated_button.dart @@ -52,14 +52,17 @@ import 'theme_data.dart'; /// If [onPressed] and [onLongPress] callbacks are null, then the /// button will be disabled. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample produces an enabled and a disabled ElevatedButton. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/elevated_button/elevated_button.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/expansion_panel.dart b/packages/material_ui/lib/src/expansion_panel.dart index a1690b4af005..4568979fde5d 100644 --- a/packages/material_ui/lib/src/expansion_panel.dart +++ b/packages/material_ui/lib/src/expansion_panel.dart @@ -171,14 +171,17 @@ class ExpansionPanelRadio extends ExpansionPanel { /// previously open panel, which is closing, and the previously closed panel, /// which is opening. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Here is a simple example of how to use [ExpansionPanelList]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/expansion_panel/expansion_panel_list.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -208,14 +211,17 @@ class ExpansionPanelList extends StatefulWidget { /// expand/collapse button is pushed. The [children] objects must be instances /// of [ExpansionPanelRadio]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// Here is a simple example of how to implement ExpansionPanelList.radio. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/expansion_panel/expansion_panel_list.expansion_panel_list_radio.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// const ExpansionPanelList.radio({ super.key, this.children = const [], diff --git a/packages/material_ui/lib/src/expansion_tile.dart b/packages/material_ui/lib/src/expansion_tile.dart index 8639fd7448dc..1f6b4c260a8b 100644 --- a/packages/material_ui/lib/src/expansion_tile.dart +++ b/packages/material_ui/lib/src/expansion_tile.dart @@ -34,8 +34,7 @@ const Duration _kExpand = Duration(milliseconds: 200); /// or look up the tile's automatically created [ExpansionTileController] /// with [ExpansibleController.of]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Typical usage of the [ExpansibleController.of] function is to call it from within the /// `build` method of a descendant of an [ExpansionTile]. @@ -48,9 +47,13 @@ const Duration _kExpand = Duration(milliseconds: 200); /// add a [Builder] widget, which provides a new scope with a /// [BuildContext] that is "under" the [ExpansionTile]: /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/expansion_tile/expansion_tile.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// A more efficient solution is to split your build function into /// several widgets. This introduces a new context from which you @@ -89,25 +92,31 @@ typedef ExpansionTileController = ExpansibleController; /// (i.e. the trailing edge). This can be changed using [controlAffinity]. This maps /// to the [leading] and [trailing] properties of [ExpansionTile]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example demonstrates how the [ExpansionTile] icon's location and appearance /// can be customized. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/expansion_tile/expansion_tile.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example demonstrates how an [ExpansibleController] can be used to /// programmatically expand or collapse an [ExpansionTile]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/expansion_tile/expansion_tile.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Accessibility /// @@ -479,15 +488,18 @@ class ExpansionTile extends StatefulWidget { /// /// To disable the theme animation, use [AnimationStyle.noAnimation]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample showcases how to override the [ExpansionTile] expansion /// animation curve and duration using [AnimationStyle]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/expansion_tile/expansion_tile.2.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final AnimationStyle? expansionAnimationStyle; /// Whether to add button:true to the semantics if onTap is provided. diff --git a/packages/material_ui/lib/src/filled_button.dart b/packages/material_ui/lib/src/filled_button.dart index 4e9d1cce6ba5..b1a893994da9 100644 --- a/packages/material_ui/lib/src/filled_button.dart +++ b/packages/material_ui/lib/src/filled_button.dart @@ -54,15 +54,18 @@ enum _FilledButtonVariant { filled, tonal } /// /// To create a 'filled tonal' button, use [FilledButton.tonal]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample produces enabled and disabled filled and filled tonal /// buttons. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/filled_button/filled_button.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Visual density effects /// diff --git a/packages/material_ui/lib/src/filter_chip.dart b/packages/material_ui/lib/src/filter_chip.dart index 2c4fe2c0145f..81b1b862a403 100644 --- a/packages/material_ui/lib/src/filter_chip.dart +++ b/packages/material_ui/lib/src/filter_chip.dart @@ -36,14 +36,17 @@ enum _ChipVariant { flat, elevated } /// /// Requires one of its ancestors to be a [Material] widget. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to use [FilterChip]s to filter through exercises. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/filter_chip/filter_chip.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Material Design 3 /// diff --git a/packages/material_ui/lib/src/flexible_space_bar.dart b/packages/material_ui/lib/src/flexible_space_bar.dart index 496f21305c80..c082bfa1ead1 100644 --- a/packages/material_ui/lib/src/flexible_space_bar.dart +++ b/packages/material_ui/lib/src/flexible_space_bar.dart @@ -60,8 +60,7 @@ enum StretchMode { /// [FlexibleSpaceBar.createSettings], to convey sizing information down to the /// [FlexibleSpaceBar]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample application demonstrates the different features of the /// [FlexibleSpaceBar] when used in a [SliverAppBar]. This app bar is configured @@ -70,9 +69,13 @@ enum StretchMode { /// `zoomBackground`. The app bar also makes use of [CollapseMode.parallax] by /// default. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/flexible_space_bar/flexible_space_bar.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/floating_action_button.dart b/packages/material_ui/lib/src/floating_action_button.dart index 3b271afa5856..b3a9f1d9509f 100644 --- a/packages/material_ui/lib/src/floating_action_button.dart +++ b/packages/material_ui/lib/src/floating_action_button.dart @@ -49,37 +49,46 @@ enum _FloatingActionButtonType { regular, small, large, extended } /// disabled. Consider changing the [backgroundColor] if disabling the floating /// action button. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [FloatingActionButton] in its usual position within a /// [Scaffold]. Pressing the button cycles it through a few variations in its /// [foregroundColor], [backgroundColor], and [shape]. The button automatically /// animates its segue from one set of visual parameters to another. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/floating_action_button/floating_action_button.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows all the variants of [FloatingActionButton] widget as /// described in: https://m3.material.io/components/floating-action-button/overview. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/floating_action_button/floating_action_button.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows [FloatingActionButton] with additional color mappings as /// described in: https://m3.material.io/components/floating-action-button/overview. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/floating_action_button/floating_action_button.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/floating_action_button_location.dart b/packages/material_ui/lib/src/floating_action_button_location.dart index 6342f79d04b2..e50178119b32 100644 --- a/packages/material_ui/lib/src/floating_action_button_location.dart +++ b/packages/material_ui/lib/src/floating_action_button_location.dart @@ -467,8 +467,7 @@ abstract class FloatingActionButtonLocation { /// You can create your own subclass of [StandardFabLocation] /// to implement a custom [FloatingActionButtonLocation]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This is an example of a user-defined [FloatingActionButtonLocation]. /// @@ -482,9 +481,13 @@ abstract class FloatingActionButtonLocation { /// [FloatingActionButtonLocation] slightly different from /// [FloatingActionButtonLocation.endFloat]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/floating_action_button_location/standard_fab_location.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// abstract class StandardFabLocation extends FloatingActionButtonLocation { /// Abstract const constructor. This constructor enables subclasses to provide @@ -945,15 +948,18 @@ abstract class FloatingActionButtonAnimator { /// does not animate on entrance and exit when [FloatingActionButtonLocation] is shown /// or hidden and when transitioning between [FloatingActionButtonLocation]s. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample showcases how to override [FloatingActionButton] entrance and exit animations /// using [FloatingActionButtonAnimator.noAnimation] in [Scaffold.floatingActionButtonAnimator]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/scaffold/scaffold.floating_action_button_animator.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// static const FloatingActionButtonAnimator noAnimation = _NoAnimationFabMotionAnimator(); @override diff --git a/packages/material_ui/lib/src/icon_button.dart b/packages/material_ui/lib/src/icon_button.dart index 6c74b2acf084..1e738f847403 100644 --- a/packages/material_ui/lib/src/icon_button.dart +++ b/packages/material_ui/lib/src/icon_button.dart @@ -61,17 +61,20 @@ enum _IconButtonVariant { standard, filled, filledTonal, outlined } /// requirements in the Material Design specification. The [alignment] controls /// how the icon itself is positioned within the hit region. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows an [IconButton] that uses the Material icon "volume_up" to /// increase the volume. /// /// ![](https://flutter.github.io/assets-for-api-docs/assets/material/icon_button.png) /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/icon_button/icon_button.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ### Icon sizes /// @@ -116,8 +119,7 @@ enum _IconButtonVariant { standard, filled, filledTonal, outlined } /// the underlying [Material] along with the splash and highlight /// [InkResponse] contributed by descendant widgets. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// In this sample the icon button's background color is defined with an [Ink] /// widget whose child is an [IconButton]. The icon button's filled background @@ -126,9 +128,13 @@ enum _IconButtonVariant { standard, filled, filledTonal, outlined } /// /// ![](https://flutter.github.io/assets-for-api-docs/assets/material/icon_button_background.png) /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/icon_button/icon_button.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// Material Design 3 introduced new types (standard and contained) of [IconButton]s. /// The default [IconButton] is the standard type. To create a filled icon button, @@ -154,26 +160,32 @@ enum _IconButtonVariant { standard, filled, filledTonal, outlined } /// the [IconButton.visualDensity] is set to [VisualDensity.compact]. Users can /// customize it by using [IconButtonTheme], [IconButton.style] or [IconButton.visualDensity]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows creation of [IconButton] widgets for standard, filled, /// filled tonal and outlined types, as described in: https://m3.material.io/components/icon-buttons/overview /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/icon_button/icon_button.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows creation of [IconButton] widgets with toggle feature for /// standard, filled, filled tonal and outlined types, as described /// in: https://m3.material.io/components/icon-buttons/overview /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/icon_button/icon_button.3.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/ink_decoration.dart b/packages/material_ui/lib/src/ink_decoration.dart index 5414d9c652f0..508945491d0b 100644 --- a/packages/material_ui/lib/src/ink_decoration.dart +++ b/packages/material_ui/lib/src/ink_decoration.dart @@ -117,8 +117,7 @@ import 'material.dart'; /// /// What to do if you want to clip this [Ink.image]? /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Wrapping the [Ink] in a clipping widget directly will not work since the /// [Material] it will be printed on is responsible for clipping. @@ -127,20 +126,27 @@ import 'material.dart'; /// it is being rendered onto the Scaffold body Material, which isn't wrapped in /// the [ClipRRect]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/ink/ink.image_clip.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// One solution would be to deliberately wrap the [Ink.image] in a [Material]. /// This makes sure the Material that the image is painted on is also responsible /// for clipping said content. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/ink/ink.image_clip.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/ink_well.dart b/packages/material_ui/lib/src/ink_well.dart index 69abb76f5ee0..5e6ed79c7331 100644 --- a/packages/material_ui/lib/src/ink_well.dart +++ b/packages/material_ui/lib/src/ink_well.dart @@ -1487,15 +1487,18 @@ class _InkResponseState extends State<_InkResponseStateWidget> /// /// An example of this situation is as follows: /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Tap the container to cause it to grow. Then, tap it again and hold before /// the widget reaches its maximum size to observe the clipped ink splash. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/ink_well/ink_well.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// An InkWell's splashes will not properly update to conform to changes if the /// size of its underlying [Material], where the splashes are rendered, changes diff --git a/packages/material_ui/lib/src/input_border.dart b/packages/material_ui/lib/src/input_border.dart index 123e8fb269c6..a18176ee3c18 100644 --- a/packages/material_ui/lib/src/input_border.dart +++ b/packages/material_ui/lib/src/input_border.dart @@ -589,15 +589,18 @@ class OutlineInputBorder extends InputBorder { /// The input decorator's "container" is the optionally filled area above the /// decorator's helper, error, and counter. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to use [ShapedInputBorder] with different /// [ShapeBorder] implementations. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/shaped_input_border/shaped_input_border.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/input_chip.dart b/packages/material_ui/lib/src/input_chip.dart index 759bc22e11e4..6f8f0d1d4356 100644 --- a/packages/material_ui/lib/src/input_chip.dart +++ b/packages/material_ui/lib/src/input_chip.dart @@ -40,29 +40,35 @@ import 'theme_data.dart'; /// * In a horizontally scrollable list, for example configured such as a /// [ListView] with [ListView.scrollDirection] set to [Axis.horizontal]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to create [InputChip]s with [onSelected] and /// [onDeleted] callbacks. When the user taps the chip, the chip will be selected. /// When the user taps the delete icon, the chip will be deleted. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/input_chip/input_chip.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// The following example shows how to generate [InputChip]s from /// user text input. When the user enters a pizza topping in the text field, /// the user is presented with a list of suggestions. When selecting one of the /// suggestions, an [InputChip] is generated in the text field. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/input_chip/input_chip.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Material Design 3 /// diff --git a/packages/material_ui/lib/src/input_decorator.dart b/packages/material_ui/lib/src/input_decorator.dart index 28a0c03d15b9..a5ed22139a58 100644 --- a/packages/material_ui/lib/src/input_decorator.dart +++ b/packages/material_ui/lib/src/input_decorator.dart @@ -2702,8 +2702,7 @@ class _InputDecoratorState extends State with TickerProviderStat /// to describe their decoration. (In fact, this class is merely the /// configuration of an [InputDecorator], which does all the heavy lifting.) /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to style a `TextField` using an `InputDecorator`. The /// TextField displays a "send message" icon to the left of the input area, @@ -2713,12 +2712,15 @@ class _InputDecoratorState extends State with TickerProviderStat /// /// ![](https://flutter.github.io/assets-for-api-docs/assets/material/input_decoration.png) /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/input_decorator/input_decoration.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to style a "collapsed" `TextField` using an /// `InputDecorator`. The collapsed `TextField` surrounds the hint text and @@ -2726,12 +2728,15 @@ class _InputDecoratorState extends State with TickerProviderStat /// /// ![](https://flutter.github.io/assets-for-api-docs/assets/material/input_decoration_collapsed.png) /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/input_decorator/input_decoration.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to create a `TextField` with hint text, a red border /// on all sides, and an error message. To display a red border and error @@ -2739,12 +2744,15 @@ class _InputDecoratorState extends State with TickerProviderStat /// /// ![](https://flutter.github.io/assets-for-api-docs/assets/material/input_decoration_error.png) /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/input_decorator/input_decoration.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to style a `TextField` with a round border and /// additional text before and after the input area. It displays "Prefix" before @@ -2752,30 +2760,40 @@ class _InputDecoratorState extends State with TickerProviderStat /// /// ![](https://flutter.github.io/assets-for-api-docs/assets/material/input_decoration_prefix_suffix.png) /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/input_decorator/input_decoration.3.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to style a `TextField` with a prefixIcon that changes color /// based on the `WidgetState`. The color defaults to gray and is green while focused. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/input_decorator/input_decoration.widget_state.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to style a `TextField` with a prefixIcon that changes color /// based on the `WidgetState` through the use of `ThemeData`. The color defaults /// to gray, be blue while focused and red if in an error state. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/input_decorator/input_decoration.widget_state.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -3011,15 +3029,18 @@ class InputDecoration { /// This can be used, for example, to add multiple [TextStyle]'s to a label that would /// otherwise be specified using [labelText], which only takes one [TextStyle]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows a `TextField` with a [Text.rich] widget as the [label]. /// The widget contains multiple [Text] widgets with different [TextStyle]'s. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/input_decorator/input_decoration.label.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// Only one of [label] and [labelText] can be specified. final Widget? label; @@ -3050,8 +3071,7 @@ class InputDecoration { /// of [InputDecoration] that changes the color of the label to the /// [InputDecoration.errorStyle] color or [ColorScheme.error]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// It's possible to override the label style for just the error state, or /// just the default state, or both. @@ -3060,9 +3080,13 @@ class InputDecoration { /// which resolves to a text style whose color depends on the decorator's /// error state. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/input_decorator/input_decoration.label_style_error.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// {@endtemplate} final TextStyle? labelStyle; @@ -3086,8 +3110,7 @@ class InputDecoration { /// When the input field receives focus, the font size of [InputDecoration.label] is /// scaled down by 75%. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// It's possible to override the label style for just the error state, or /// just the default state, or both. @@ -3096,9 +3119,13 @@ class InputDecoration { /// [WidgetStateProperty] which resolves to a text style whose color depends /// on the decorator's error state. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/input_decorator/input_decoration.floating_label_style_error.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// {@endtemplate} final TextStyle? floatingLabelStyle; @@ -3108,15 +3135,18 @@ class InputDecoration { /// the same location as [error]. If a non-null [error] or [errorText] value is /// specified then the [helper] is not shown. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows a `TextField` with a [Text.rich] widget as the [helper]. /// The widget contains [Text] and [Icon] widgets with different styles. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/input_decorator/input_decoration.helper.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// Only one of [helper] and [helperText] can be specified. final Widget? helper; @@ -3414,15 +3444,18 @@ class InputDecoration { /// The prefix icon alignment can be changed using [Align] with a fixed `widthFactor` and /// `heightFactor`. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows how the prefix icon alignment can be changed using [Align] with /// a fixed `widthFactor` and `heightFactor`. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/input_decorator/input_decoration.prefix_icon.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// See also: /// @@ -3444,8 +3477,7 @@ class InputDecoration { /// setting [isDense] to true and setting the constraints' minimum height /// and width to a value lower than the minimum tappable size. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows the differences between two `TextField` widgets when /// [prefixIconConstraints] is set to the default value and when one is not. @@ -3456,9 +3488,13 @@ class InputDecoration { /// If null, [BoxConstraints] with a minimum width and height of 48px is /// used. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/input_decorator/input_decoration.prefix_icon_constraints.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final BoxConstraints? prefixIconConstraints; /// Optional widget to place on the line before the input. @@ -3543,15 +3579,18 @@ class InputDecoration { /// The suffix icon alignment can be changed using [Align] with a fixed `widthFactor` and /// `heightFactor`. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows how the suffix icon alignment can be changed using [Align] with /// a fixed `widthFactor` and `heightFactor`. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/input_decorator/input_decoration.suffix_icon.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// See also: /// @@ -3628,8 +3667,7 @@ class InputDecoration { /// If null, a [BoxConstraints] with a minimum width and height of 48px is /// used. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows the differences between two `TextField` widgets when /// [suffixIconConstraints] is set to the default value and when one is not. @@ -3640,9 +3678,13 @@ class InputDecoration { /// If null, [BoxConstraints] with a minimum width and height of 48px is /// used. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/input_decorator/input_decoration.suffix_icon_constraints.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final BoxConstraints? suffixIconConstraints; /// Optional text to place below the line as a character count. diff --git a/packages/material_ui/lib/src/list_tile.dart b/packages/material_ui/lib/src/list_tile.dart index 5d826b614bcf..ec236dda3fad 100644 --- a/packages/material_ui/lib/src/list_tile.dart +++ b/packages/material_ui/lib/src/list_tile.dart @@ -232,59 +232,74 @@ enum ListTileTitleAlignment { /// [selectedTileColor], [focusColor], and [hoverColor] as these colors /// are not drawn by the list tile itself but by the material widget ancestor. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example showcases how [ListTile] needs to be wrapped in a [Material] /// widget to animate colors. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/list_tile/list_tile.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example uses a [ListView] to demonstrate different configurations of /// [ListTile]s in [Card]s. /// /// ![Different variations of ListTile](https://flutter.github.io/assets-for-api-docs/assets/material/list_tile.png) /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/list_tile/list_tile.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows the creation of a [ListTile] using [ThemeData.useMaterial3] flag, /// as described in: https://m3.material.io/components/lists/overview. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/list_tile/list_tile.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows [ListTile]'s [textColor] and [iconColor] can use /// [WidgetStateColor] color to change the color of the text and icon /// when the [ListTile] is enabled, selected, or disabled. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/list_tile/list_tile.3.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows [ListTile.titleAlignment] can be used to configure the /// [leading] and [trailing] widgets alignment relative to the [title] and /// [subtitle] widgets. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/list_tile/list_tile.4.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// // TODO(framework): Replace the following block with a blue example container // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 @@ -384,26 +399,32 @@ enum ListTileTitleAlignment { /// you're looking for, it's easy to create custom list items with a /// combination of other widgets, such as [Row]s and [Column]s. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Here is an example of a custom list item that resembles a YouTube-related /// video list item created with [Expanded] and [Container] widgets. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/list_tile/custom_list_item.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Here is an example of an article list item with multiline titles and /// subtitles. It utilizes [Row]s and [Column]s, as well as [Expanded] and /// [AspectRatio] widgets to organize its layout. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/list_tile/custom_list_item.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -699,16 +720,19 @@ class ListTile extends StatelessWidget { /// By default the selected color is the theme's primary color. The selected color /// can be overridden with a [ListTileTheme]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// Here is an example of using a [StatefulWidget] to keep track of the /// selected index, and using that to set the [selected] property on the /// corresponding [ListTile]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/list_tile/list_tile.selected.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final bool selected; /// The color for the tile's [Material] when it has the input focus. diff --git a/packages/material_ui/lib/src/material_state.dart b/packages/material_ui/lib/src/material_state.dart index ec3c0b311bd6..aca777ac4b6f 100644 --- a/packages/material_ui/lib/src/material_state.dart +++ b/packages/material_ui/lib/src/material_state.dart @@ -161,15 +161,18 @@ typedef MaterialStateColor = WidgetStateColor; /// To use a [MaterialStateMouseCursor], you should create a subclass of /// [MaterialStateMouseCursor] and implement the abstract `resolve` method. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example defines a mouse cursor that resolves to /// [SystemMouseCursors.forbidden] when its widget is disabled. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/material_state/material_state_mouse_cursor.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// This class should only be used for parameters which are documented to take /// [MaterialStateMouseCursor], otherwise only the default state will be used. @@ -199,15 +202,18 @@ typedef MaterialStateMouseCursor = WidgetStateMouseCursor; /// property values. [MaterialStateBorderSide] should only be used with widgets that document /// their support, like [ActionChip.side]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example defines a subclass of [MaterialStateBorderSide], that resolves /// to a red border side when its widget is selected. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/material_state/material_state_border_side.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// This class should only be used for parameters which are documented to take /// [MaterialStateBorderSide], otherwise only the default state will be used. @@ -230,16 +236,19 @@ typedef MaterialStateBorderSide = WidgetStateBorderSide; /// [OutlinedBorder] and implement [MaterialStateOutlinedBorder]'s abstract /// `resolve` method. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example defines a subclass of [RoundedRectangleBorder] and an /// implementation of [MaterialStateOutlinedBorder], that resolves to /// [RoundedRectangleBorder] when its widget is selected. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/material_state/material_state_outlined_border.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// This class should only be used for parameters which are documented to take /// [MaterialStateOutlinedBorder], otherwise only the default state will be used. @@ -469,15 +478,18 @@ class _MaterialStateUnderlineInputBorder extends MaterialStateUnderlineInputBord /// resolves the input border in the given states. /// 3. Using [WidgetStateInputBorder.fromMap] to assign a border with a [WidgetStateMap]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to use [WidgetStateInputBorder] to create /// a [TextField] with an appearance that responds to user interaction. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/widget_state_input_border/widget_state_input_border.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// abstract interface class WidgetStateInputBorder implements InputBorder, WidgetStateProperty { /// Creates a [WidgetStateInputBorder] using a [WidgetPropertyResolver] @@ -536,8 +548,7 @@ class _WidgetInputBorderMapper extends WidgetStateMapper /// of their current material state and [resolve] the button style's /// material state properties when their value is needed. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how you can override the default text and icon /// color (the "foreground color") of a [TextButton] with a @@ -545,9 +556,13 @@ class _WidgetInputBorderMapper extends WidgetStateMapper /// will be `Colors.blue` when the button is being pressed, hovered, /// or focused. Otherwise, the text color will be `Colors.red`. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/material_state/material_state_property.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/menu_anchor.dart b/packages/material_ui/lib/src/menu_anchor.dart index 817cefa2a8aa..b33643255c83 100644 --- a/packages/material_ui/lib/src/menu_anchor.dart +++ b/packages/material_ui/lib/src/menu_anchor.dart @@ -211,38 +211,47 @@ class _TweenCurve extends Curve { /// to retrieve the controller for the closest [MenuAnchor] ancestor of a given [BuildContext]. /// More detailed usage of [MenuController] is available in its class documentation. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to use a [MenuAnchor] to wrap a button and open a /// cascading menu from the button. This example also shows how to use /// [onAnimationStatusChanged] to track animation status and toggle the menu. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/menu_anchor/menu_anchor.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to use a [MenuAnchor] to create a cascading context /// menu in a region of the view, positioned where the user clicks the mouse /// with Ctrl pressed. The [anchorTapClosesMenu] attribute is set to true so /// that clicks on the [MenuAnchor] area will cause the menus to be closed. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/menu_anchor/menu_anchor.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example demonstrates a simplified cascading menu using the [MenuAnchor] /// widget. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/menu_anchor/menu_anchor.3.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// The [MenuStyle.visualDensity] setting only affects horizontal padding, /// and it will never make it negative. Vertical padding is not affected at all. @@ -825,16 +834,20 @@ class _MenuAnchorState extends State with SingleTickerProviderStateM /// sure that selecting a menu item and triggering the shortcut do the same /// thing, it is recommended that they call the same callback. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// +/// /// This example shows a [MenuBar] that contains a single top /// level menu, containing three items: "About", a checkbox menu item for /// showing a message, and "Quit". The items are identified with an enum value, /// and the shortcuts are registered globally with the [ShortcutRegistry]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/menu_anchor/menu_bar.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// {@endtemplate} /// /// {@macro flutter.material.MenuAcceleratorLabel.accelerator_sample} @@ -1347,15 +1360,18 @@ class _MenuItemButtonState extends State { /// To style the checkbox separately from the button, add a [CheckboxTheme] /// ancestor. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a menu with a checkbox that shows a message in the body /// of the app if checked. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/menu_anchor/checkbox_menu_button.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -1546,15 +1562,18 @@ class CheckboxMenuButton extends StatelessWidget { /// To style the radio button separately from the overall button, add a /// [RadioTheme] ancestor. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a menu with three radio buttons with shortcuts that /// changes the background color of the body when the buttons are selected. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/menu_anchor/radio_menu_button.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -2941,8 +2960,8 @@ typedef MenuAcceleratorChildBuilder = /// not necessary to provide one. /// /// {@template flutter.material.MenuAcceleratorLabel.accelerator_sample} -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// +/// /// This example shows a [MenuBar] that handles keyboard /// accelerators using [MenuAcceleratorLabel]. To use the accelerators, press /// the Alt key to see which letters are underlined in the menu bar, and then @@ -2950,9 +2969,13 @@ typedef MenuAcceleratorChildBuilder = /// since those platforms don't support them natively, so this demo will only /// show a regular Material menu bar on those platforms. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/menu_anchor/menu_accelerator_label.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// {@endtemplate} class MenuAcceleratorLabel extends StatefulWidget { /// Creates a const [MenuAcceleratorLabel]. diff --git a/packages/material_ui/lib/src/navigation_bar.dart b/packages/material_ui/lib/src/navigation_bar.dart index 69aa716f71fd..f657ff9126a2 100644 --- a/packages/material_ui/lib/src/navigation_bar.dart +++ b/packages/material_ui/lib/src/navigation_bar.dart @@ -54,8 +54,7 @@ const double _kMaxLabelTextScaleFactor = 1.3; /// This widget holds a collection of destinations (usually /// [NavigationDestination]s). /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [NavigationBar] as it is used within a [Scaffold] /// widget. The [NavigationBar] has three [NavigationDestination] widgets and @@ -63,23 +62,29 @@ const double _kMaxLabelTextScaleFactor = 1.3; /// callback changes the selected item's index and displays a corresponding /// widget in the body of the [Scaffold]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/navigation_bar/navigation_bar.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example showcases [NavigationBar] label behaviors. When tapping on one /// of the label behavior options, the [labelBehavior] of the [NavigationBar] /// will be updated. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/navigation_bar/navigation_bar.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [NavigationBar] within a main [Scaffold] /// widget that's used to control the visibility of destination pages. @@ -94,9 +99,14 @@ const double _kMaxLabelTextScaleFactor = 1.3; /// fades in the new one. Destinations that aren't visible or animating /// are kept [Offstage]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/navigation_bar/navigation_bar.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// +/// /// See also: /// /// * [NavigationDestination] diff --git a/packages/material_ui/lib/src/navigation_drawer.dart b/packages/material_ui/lib/src/navigation_drawer.dart index 46f118ddad18..e7fe8154ad8c 100644 --- a/packages/material_ui/lib/src/navigation_drawer.dart +++ b/packages/material_ui/lib/src/navigation_drawer.dart @@ -33,8 +33,7 @@ import 'theme.dart'; /// They are treated as a group and when one is selected, the [onDestinationSelected] /// is called with the index into the group that corresponds to the selected destination. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [NavigationDrawer] used within a [Scaffold] /// widget. The [NavigationDrawer] has headline widget, divider widget and three @@ -42,9 +41,13 @@ import 'theme.dart'; /// The [onDestinationSelected] callback changes the selected item's index and displays /// a corresponding widget in the body of the [Scaffold]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/navigation_drawer/navigation_drawer.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/navigation_rail.dart b/packages/material_ui/lib/src/navigation_rail.dart index 703a4c62ea06..956fddbb2113 100644 --- a/packages/material_ui/lib/src/navigation_rail.dart +++ b/packages/material_ui/lib/src/navigation_rail.dart @@ -48,15 +48,18 @@ const double _kIndicatorHeight = 32; /// [the adaptive_scaffold.dart sample](https://github.com/flutter/demos/blob/main/web_dashboard/lib/src/widgets/third_party/adaptive_scaffold.dart) /// for an example. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows the creation of [NavigationRail] widget used within a Scaffold with 3 /// [NavigationRailDestination]s, as described in: https://m3.material.io/components/navigation-rail/overview /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/navigation_rail/navigation_rail.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -378,8 +381,7 @@ class NavigationRail extends StatefulWidget { /// This can be used to synchronize animations in the [leading] or [trailing] /// widget, such as an animated menu or a [FloatingActionButton] animation. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows how to use this animation to create a [FloatingActionButton] /// that animates itself between the normal and extended states of the @@ -388,9 +390,13 @@ class NavigationRail extends StatefulWidget { /// An instance of `MyNavigationRailFab` is created for [NavigationRail.leading]. /// Pressing the FAB button toggles the "extended" state of the [NavigationRail]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/navigation_rail/navigation_rail.extended_animation.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// static Animation extendedAnimation(BuildContext context) { return context .dependOnInheritedWidgetOfExactType<_ExtendedNavigationRailAnimation>()! diff --git a/packages/material_ui/lib/src/outlined_button.dart b/packages/material_ui/lib/src/outlined_button.dart index 63ae4d37c90e..0c345f5a15c6 100644 --- a/packages/material_ui/lib/src/outlined_button.dart +++ b/packages/material_ui/lib/src/outlined_button.dart @@ -53,14 +53,17 @@ import 'theme_data.dart'; /// appearance of its outline, both the [ButtonStyle.shape] and /// [ButtonStyle.side] properties must be specified. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Here is an example of a basic [OutlinedButton]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/outlined_button/outlined_button.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// The static [styleFrom] method is a convenient way to create a /// outlined button [ButtonStyle] from simple values. diff --git a/packages/material_ui/lib/src/page_transitions_theme.dart b/packages/material_ui/lib/src/page_transitions_theme.dart index 00fb9e07a06c..47bf20c4bac8 100644 --- a/packages/material_ui/lib/src/page_transitions_theme.dart +++ b/packages/material_ui/lib/src/page_transitions_theme.dart @@ -428,14 +428,17 @@ class _FadeForwardsPageTransition extends StatelessWidget { /// transition animation that looks like the default page transition /// used on Android U. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows the default page transition on Android. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/page_transitions_theme/page_transitions_theme.3.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -610,15 +613,18 @@ class ZoomPageTransitionsBuilder extends PageTransitionsBuilder { /// while the route animation plays may appear frozen - unless they are a hero /// animation or something that is drawn in a separate overlay. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows a [MaterialApp] that disables snapshotting for the zoom /// transitions on Android. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/page_transitions_theme/page_transitions_theme.1.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// See also: /// @@ -736,14 +742,17 @@ class ZoomPageTransitionsBuilder extends PageTransitionsBuilder { /// If a builder with a matching platform is not found, then the /// [ZoomPageTransitionsBuilder] is used. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [MaterialApp] that defines a custom [PageTransitionsTheme]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/page_transitions_theme/page_transitions_theme.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/paginated_data_table.dart b/packages/material_ui/lib/src/paginated_data_table.dart index d346cf46c821..ab6d049aa46d 100644 --- a/packages/material_ui/lib/src/paginated_data_table.dart +++ b/packages/material_ui/lib/src/paginated_data_table.dart @@ -38,8 +38,7 @@ import 'theme.dart'; /// If the [key] is a [PageStorageKey], the [initialFirstRowIndex] is persisted /// to [PageStorage]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// /// This sample shows how to display a [DataTable] with three columns: name, @@ -47,19 +46,26 @@ import 'theme.dart'; /// table contains three rows of data for three example users, the data for /// which is defined by three [DataRow] objects. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/paginated_data_table/paginated_data_table.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// /// This example shows how paginated data tables can supported sorted data. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/paginated_data_table/paginated_data_table.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/popup_menu.dart b/packages/material_ui/lib/src/popup_menu.dart index c933e06ed56b..00630cd30ecb 100644 --- a/packages/material_ui/lib/src/popup_menu.dart +++ b/packages/material_ui/lib/src/popup_menu.dart @@ -1303,44 +1303,56 @@ typedef PopupMenuItemBuilder = List> Function(BuildContext /// Use the sample below for an example of migrating from [PopupMenuButton] to /// [MenuAnchor]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a menu with three items, selecting between an enum's /// values and setting a `selectedMenu` field based on the selection. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/popup_menu/popup_menu.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to migrate the above to a [MenuAnchor]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/menu_anchor/menu_anchor.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows the creation of a popup menu, as described in: /// https://m3.material.io/components/menus/overview /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/popup_menu/popup_menu.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample showcases how to override the [PopupMenuButton] animation /// curves and duration using [AnimationStyle]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/popup_menu/popup_menu.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/progress_indicator.dart b/packages/material_ui/lib/src/progress_indicator.dart index 7a488475f3cd..41810b920a73 100644 --- a/packages/material_ui/lib/src/progress_indicator.dart +++ b/packages/material_ui/lib/src/progress_indicator.dart @@ -384,27 +384,33 @@ class _LinearProgressIndicatorPainter extends CustomPainter { /// The minimum height of the indicator can be specified using [minHeight]. /// The indicator can be made taller by wrapping the widget with a [SizedBox]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example showcases determinate and indeterminate [LinearProgressIndicator]s. /// The [LinearProgressIndicator]s will use the ![updated Material 3 Design appearance](https://m3.material.io/components/progress-indicators/overview) /// when setting the [LinearProgressIndicator.year2023] flag to false. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/progress_indicator/linear_progress_indicator.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows the creation of a [LinearProgressIndicator] with a changing value. /// When toggling the switch, [LinearProgressIndicator] uses a determinate value. /// As described in: https://m3.material.io/components/progress-indicators/overview /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/progress_indicator/linear_progress_indicator.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// {@macro flutter.material.ProgressIndicator.AnimationSynchronization} /// @@ -809,27 +815,33 @@ class _CircularProgressIndicatorPainter extends CustomPainter { /// The indicator arc is displayed with [valueColor], an animated value. To /// specify a constant color use: `AlwaysStoppedAnimation(color)`. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example showcases determinate and indeterminate [CircularProgressIndicator]s. /// The [CircularProgressIndicator]s will use the ![updated Material 3 Design appearance](https://m3.material.io/components/progress-indicators/overview) /// when setting the [CircularProgressIndicator.year2023] flag to false. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/progress_indicator/circular_progress_indicator.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows the creation of a [CircularProgressIndicator] with a changing value. /// When toggling the switch, [CircularProgressIndicator] uses a determinate value. /// As described in: https://m3.material.io/components/progress-indicators/overview /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/progress_indicator/circular_progress_indicator.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// {@template flutter.material.ProgressIndicator.AnimationSynchronization} /// ## Animation synchronization @@ -851,8 +863,7 @@ class _CircularProgressIndicatorPainter extends CustomPainter { /// [controller] property of an individual indicator. /// {@endtemplate} /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample demonstrates how to synchronize the indeterminate animations /// of multiple [CircularProgressIndicator]s using a [Theme]. @@ -865,9 +876,13 @@ class _CircularProgressIndicatorPainter extends CustomPainter { /// This forces each indicator to create its own internal controller, /// causing their animations to become desynchronized. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/progress_indicator/circular_progress_indicator.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/radio.dart b/packages/material_ui/lib/src/radio.dart index 4220a4d8273c..013446cd75e7 100644 --- a/packages/material_ui/lib/src/radio.dart +++ b/packages/material_ui/lib/src/radio.dart @@ -44,8 +44,7 @@ const double _kInnerRadius = 4.5; /// [RadioGroup.groupValue], and the [Radio] under it with matching [value] /// will be selected. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Here is an example of Radio widgets wrapped in ListTiles, which is similar /// to what you could get with the RadioListTile widget. @@ -62,12 +61,15 @@ const double _kInnerRadius = 4.5; /// /// Requires one of its ancestors to be a [Material] widget. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/radio/radio.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Here is an example of how the you can override the default theme of a /// [Radio] with [WidgetStateProperty]. @@ -79,9 +81,13 @@ const double _kInnerRadius = 4.5; /// - The third [Radio] customizes the [side] property to display a different border color /// when selected or unselected. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/radio/radio.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -248,15 +254,18 @@ class Radio extends StatefulWidget { /// {@macro flutter.widget.RawRadio.toggleable} /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows how to enable deselecting a radio button by setting the /// [toggleable] attribute. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/radio/radio.toggleable.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final bool toggleable; /// The color to use when this radio button is selected. diff --git a/packages/material_ui/lib/src/radio_list_tile.dart b/packages/material_ui/lib/src/radio_list_tile.dart index 4e2e76230634..3d93ed9bcd62 100644 --- a/packages/material_ui/lib/src/radio_list_tile.dart +++ b/packages/material_ui/lib/src/radio_list_tile.dart @@ -89,27 +89,33 @@ enum _RadioType { material, adaptive } /// is expensive. Consider only wrapping the [RadioListTile]s that require it /// or include a common [Material] ancestor where possible. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// ![RadioListTile sample](https://flutter.github.io/assets-for-api-docs/assets/material/radio_list_tile.png) /// /// This widget shows a pair of radio buttons that control the `_character` /// field. The field is of the type `SingingCharacter`, an enum. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/radio_list_tile/radio_list_tile.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample demonstrates how [RadioListTile] positions the radio widget /// relative to the text in different configurations. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/radio_list_tile/radio_list_tile.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Semantics in RadioListTile /// @@ -128,8 +134,7 @@ enum _RadioType { material, adaptive } /// into one. Therefore, it may be necessary to create a custom radio tile /// widget to accommodate similar use cases. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// ![Radio list tile semantics sample](https://flutter.github.io/assets-for-api-docs/assets/material/radio_list_tile_semantics.png) /// @@ -137,9 +142,13 @@ enum _RadioType { material, adaptive } /// LinkedLabelRadio, that includes an interactive [RichText] widget that /// handles tap gestures. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/radio_list_tile/custom_labeled_radio.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## RadioListTile isn't exactly what I want /// @@ -148,17 +157,20 @@ enum _RadioType { material, adaptive } /// combining [Radio] with other widgets, such as [Text], [Padding] and /// [InkWell]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// ![Custom radio list tile sample](https://flutter.github.io/assets-for-api-docs/assets/material/radio_list_tile_custom.png) /// /// Here is an example of a custom LabeledRadio widget, but you can easily /// make your own configurable widget. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/radio_list_tile/custom_labeled_radio.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -368,15 +380,18 @@ class RadioListTile extends StatefulWidget { /// /// The default is false. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows how to enable deselecting a radio button by setting the /// [toggleable] attribute. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/radio_list_tile/radio_list_tile.toggleable.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final bool toggleable; /// The color to use when this radio button is selected. diff --git a/packages/material_ui/lib/src/range_slider.dart b/packages/material_ui/lib/src/range_slider.dart index 44d5b8b277b8..518a1f944cba 100644 --- a/packages/material_ui/lib/src/range_slider.dart +++ b/packages/material_ui/lib/src/range_slider.dart @@ -47,8 +47,7 @@ typedef PaintRangeValueIndicator = void Function(PaintingContext context, Offset /// /// {@youtube 560 315 https://www.youtube.com/watch?v=ufb4gIPDmEs} /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// ![A range slider widget, consisting of 5 divisions and showing the default /// value indicator.](https://flutter.github.io/assets-for-api-docs/assets/material/range_slider.png) @@ -57,9 +56,13 @@ typedef PaintRangeValueIndicator = void Function(PaintingContext context, Offset /// divisions, from 0 to 100. This means are values are split between 0, 20, 40, /// 60, 80, and 100. The range values are initialized with 40 and 80 in this demo. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/range_slider/range_slider.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// A range slider can be used to select from either a continuous or a discrete /// set of values. The default is to use a continuous range of values from [min] diff --git a/packages/material_ui/lib/src/refresh_indicator.dart b/packages/material_ui/lib/src/refresh_indicator.dart index 9f75f6e7f0ba..1ea658429b7c 100644 --- a/packages/material_ui/lib/src/refresh_indicator.dart +++ b/packages/material_ui/lib/src/refresh_indicator.dart @@ -87,33 +87,42 @@ enum _IndicatorType { material, adaptive, noSpinner } /// /// The trigger mode is configured by [RefreshIndicator.triggerMode]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how [RefreshIndicator] can be triggered in different ways. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/refresh_indicator/refresh_indicator.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to trigger [RefreshIndicator] in a nested scroll view using /// the [notificationPredicate] property. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/refresh_indicator/refresh_indicator.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to use [RefreshIndicator] without the spinner. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/refresh_indicator/refresh_indicator.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Troubleshooting /// diff --git a/packages/material_ui/lib/src/reorderable_list.dart b/packages/material_ui/lib/src/reorderable_list.dart index becfbf5e5c16..926942a86bff 100644 --- a/packages/material_ui/lib/src/reorderable_list.dart +++ b/packages/material_ui/lib/src/reorderable_list.dart @@ -26,13 +26,16 @@ import 'theme.dart'; /// The [onReorderItem] parameter will be called when a child /// widget is dragged to a new position. /// +/// +/// +/// // TODO(framework): Replace the following block with a @dartpad directive // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 -/// +/// {@macro material_ui.dartpad_guide} /// /// {@example /example/lib/reorderable_list/reorderable_list_view.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// By default, on [TargetPlatformVariant.desktop] platforms each item will /// have a drag handle added on top of it that will allow the user to grab it @@ -46,8 +49,7 @@ import 'theme.dart'; /// This example demonstrates using the [ReorderableListView.proxyDecorator] callback /// to customize the appearance of a list item while it's being dragged. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// While a drag is underway, the widget returned by the [ReorderableListView.proxyDecorator] /// callback serves as a "proxy" (a substitute) for the item in the list. The proxy is @@ -55,23 +57,30 @@ import 'theme.dart'; /// callback in this example is similar to the default one except that it changes the /// proxy item's background color. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/reorderable_list/reorderable_list_view.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// This example demonstrates using the [ReorderableListView.proxyDecorator] callback to /// customize the appearance of a [Card] while it's being dragged. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// The default [proxyDecorator] wraps the dragged item in a [Material] widget and animates /// its elevation. This example demonstrates how to use the [ReorderableListView.proxyDecorator] /// callback to update the dragged card elevation without inserted a new [Material] widget. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/reorderable_list/reorderable_list_view.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// class ReorderableListView extends StatefulWidget { /// Creates a reorderable list from a pre-built list of widgets. /// @@ -163,13 +172,17 @@ class ReorderableListView extends StatefulWidget { /// This example creates a list using the /// [ReorderableListView.builder] constructor. Using the [IndexedWidgetBuilder], The /// list items are built lazily on demand. + /// + /// + /// // TODO(framework): Replace the following block with a @dartpad directive // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 - /// + /// {@macro material_ui.dartpad_guide} /// /// {@example /example/lib/reorderable_list/reorderable_list_view.reorderable_list_view_builder.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// + /// /// See also: /// /// * [ReorderableListView], which allows you to build a reorderable @@ -273,14 +286,17 @@ class ReorderableListView extends StatefulWidget { /// The following sample specifies `buildDefaultDragHandles: false`, and /// uses a [Card] at the leading edge of each item for the item's drag handle. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// + /// /// /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} /// /// {@example /example/lib/reorderable_list/reorderable_list_view.build_default_drag_handles.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final bool buildDefaultDragHandles; /// {@macro flutter.widgets.reorderable_list.padding} diff --git a/packages/material_ui/lib/src/scaffold.dart b/packages/material_ui/lib/src/scaffold.dart index 3ebc163a0455..395a4de2c2ff 100644 --- a/packages/material_ui/lib/src/scaffold.dart +++ b/packages/material_ui/lib/src/scaffold.dart @@ -94,14 +94,17 @@ enum _ScaffoldSlot { /// Scaffolds, set a new scope by instantiating a new ScaffoldMessenger in /// between the levels of nesting. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Here is an example of showing a [SnackBar] when the user presses a button. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/scaffold/scaffold_messenger.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -124,15 +127,18 @@ class ScaffoldMessenger extends StatefulWidget { /// The state from the closest instance of this class that encloses the given /// context. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// Typical usage of the [ScaffoldMessenger.of] function is to call it in /// response to a user gesture or an application state change. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/scaffold/scaffold_messenger.of.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// A less elegant but more expedient solution is to assign a [GlobalKey] to the /// [ScaffoldMessenger], then use the `key.currentState` property to obtain the @@ -140,8 +146,7 @@ class ScaffoldMessenger extends StatefulWidget { /// function. The [MaterialApp.scaffoldMessengerKey] refers to the root /// ScaffoldMessenger that is provided by default. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// Sometimes [SnackBar]s are produced by code that doesn't have ready access /// to a valid [BuildContext]. One such example of this is when you show a @@ -150,9 +155,13 @@ class ScaffoldMessenger extends StatefulWidget { /// example shows a key being used to obtain the [ScaffoldMessengerState] /// provided by the [MaterialApp]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/scaffold/scaffold_messenger.of.1.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// If there is no [ScaffoldMessenger] in scope, then this will assert in /// debug mode, and throw an exception in release mode. @@ -275,14 +284,17 @@ class ScaffoldMessengerState extends State with TickerProvide /// See [ScaffoldMessenger.of] for information about how to obtain the /// [ScaffoldMessengerState]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// Here is an example of showing a [SnackBar] when the user presses a button. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/scaffold/scaffold_messenger_state.show_snack_bar.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// ## Relative positioning of floating SnackBars /// @@ -294,23 +306,29 @@ class ScaffoldMessengerState extends State with TickerProvide /// In this case, consider constraining the size of these widgets to allow room for /// the SnackBar to be visible. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// Here is an example showing how to display a [SnackBar] with [showSnackBar] /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/scaffold/scaffold_messenger_state.show_snack_bar.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// Here is an example showing that a floating [SnackBar] appears above [Scaffold.floatingActionButton]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/scaffold/scaffold_messenger_state.show_snack_bar.1.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// If [AnimationStyle.duration] is provided in the [snackBarAnimationStyle] /// parameter, it will be used to override the snackbar show animation duration. @@ -322,15 +340,18 @@ class ScaffoldMessengerState extends State with TickerProvide /// /// To disable the snackbar animation, use [AnimationStyle.noAnimation]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample showcases how to override [SnackBar] show and hide animation /// duration using [AnimationStyle] in [ScaffoldMessengerState.showSnackBar]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/scaffold/scaffold_messenger_state.show_snack_bar.2.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// ScaffoldFeatureController showSnackBar( SnackBar snackBar, { @@ -512,14 +533,17 @@ class ScaffoldMessengerState extends State with TickerProvide /// See [ScaffoldMessenger.of] for information about how to obtain the /// [ScaffoldMessengerState]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// Here is an example of showing a [MaterialBanner] when the user presses a button. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/scaffold/scaffold_messenger_state.show_material_banner.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// ScaffoldFeatureController showMaterialBanner( MaterialBanner materialBanner, ) { @@ -1575,20 +1599,22 @@ class _FloatingActionButtonTransitionState extends State<_FloatingActionButtonTr /// [ScaffoldState] for the current [BuildContext] via [Scaffold.of] and use the /// [ScaffoldState.showBottomSheet] function. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [Scaffold] with a [body] and [FloatingActionButton]. /// The [body] is a [Text] placed in a [Center] in order to center the text /// within the [Scaffold]. The [FloatingActionButton] is connected to a /// callback that increments a counter. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/scaffold/scaffold.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [Scaffold] with a blueGrey [backgroundColor], [body] /// and [FloatingActionButton]. The [body] is a [Text] placed in a [Center] in @@ -1597,12 +1623,15 @@ class _FloatingActionButtonTransitionState extends State<_FloatingActionButtonTr /// /// ![](https://flutter.github.io/assets-for-api-docs/assets/material/scaffold_background_color.png) /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/scaffold/scaffold.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [Scaffold] with an [AppBar], a [BottomAppBar] and a /// [FloatingActionButton]. The [body] is a [Text] placed in a [Center] in order @@ -1613,9 +1642,13 @@ class _FloatingActionButtonTransitionState extends State<_FloatingActionButtonTr /// /// ![](https://flutter.github.io/assets-for-api-docs/assets/material/scaffold_bottom_app_bar.png) /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/scaffold/scaffold.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Scaffold layout, the keyboard, and display "notches" /// @@ -1870,17 +1903,20 @@ class Scaffold extends StatefulWidget { /// To close the drawer, use either [ScaffoldState.closeDrawer], [Navigator.pop] /// or press the escape key on the keyboard. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// To disable the drawer edge swipe on mobile, set the /// [Scaffold.drawerEnableOpenDragGesture] to false. Then, use /// [ScaffoldState.openDrawer] to open the drawer and [Navigator.pop] to close /// it. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/scaffold/scaffold.drawer.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final Widget? drawer; /// Optional callback that is called when the [Scaffold.drawer] is opened or closed. @@ -1897,17 +1933,20 @@ class Scaffold extends StatefulWidget { /// To close the drawer, use either [ScaffoldState.closeEndDrawer], [Navigator.pop] /// or press the escape key on the keyboard. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// To disable the drawer edge swipe, set the /// [Scaffold.endDrawerEnableOpenDragGesture] to false. Then, use /// [ScaffoldState.openEndDrawer] to open the drawer and [Navigator.pop] to /// close it. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/scaffold/scaffold.end_drawer.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final Widget? endDrawer; /// Optional callback that is called when the [Scaffold.endDrawer] is opened or closed. @@ -2054,18 +2093,20 @@ class Scaffold extends StatefulWidget { /// /// This method can be expensive (it walks the element tree). /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// Typical usage of the [Scaffold.of] function is to call it from within the /// `build` method of a child of a [Scaffold]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/scaffold/scaffold.of.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// When the [Scaffold] is actually created in the same `build` function, the /// `context` argument to the `build` function can't be used to find the @@ -2074,9 +2115,13 @@ class Scaffold extends StatefulWidget { /// to provide a new scope with a [BuildContext] that is "under" the /// [Scaffold]: /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/scaffold/scaffold.of.1.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// A more efficient solution is to split your build function into several /// widgets. This introduces a new context from which you can obtain the @@ -2662,16 +2707,19 @@ class ScaffoldState extends State /// of the app. Modal bottom sheets can be created and displayed with the /// [showModalBottomSheet] function. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example demonstrates how to use [showBottomSheet] to display a /// bottom sheet when a user taps a button. It also demonstrates how to /// close a bottom sheet using the Navigator. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/scaffold/scaffold_state.show_bottom_sheet.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// The [sheetAnimationStyle] parameter is used to override the bottom sheet /// animation duration and reverse animation duration. @@ -2686,15 +2734,19 @@ class ScaffoldState extends State /// /// To disable the bottom sheet animation, use [AnimationStyle.noAnimation]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample showcases how to override the [showBottomSheet] animation /// duration and reverse animation duration using [AnimationStyle]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/scaffold/scaffold_state.show_bottom_sheet.1.dart} /// - // TODO(framework): End of the @dartpad directive. + /// + /// /// See also: /// /// * [BottomSheet], which becomes the parent of the widget returned by the diff --git a/packages/material_ui/lib/src/scrollbar.dart b/packages/material_ui/lib/src/scrollbar.dart index a724efff7280..c19f2bb6a5e1 100644 --- a/packages/material_ui/lib/src/scrollbar.dart +++ b/packages/material_ui/lib/src/scrollbar.dart @@ -33,19 +33,21 @@ const Duration _kScrollbarTimeToFade = Duration(milliseconds: 600); /// or [WidgetState.hovered] on desktop and web platforms. These stateful /// color choices can be changed using [ScrollbarThemeData.thumbColor]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows a [Scrollbar] that executes a fade animation as scrolling /// occurs. The Scrollbar will fade into view as the user scrolls, and fade out /// when scrolling stops. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/scrollbar/scrollbar.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// When [thumbVisibility] is true, the scrollbar thumb will remain visible /// without the fade animation. This requires that a [ScrollController] is @@ -55,9 +57,13 @@ const Duration _kScrollbarTimeToFade = Duration(milliseconds: 600); /// that the [Scrollbar] is always visible, since scrolling in the horizontal /// axis is less discoverable. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/scrollbar/scrollbar.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// A scrollbar track can be added using [trackVisibility]. This can also be /// drawn when triggered by a hover event, or based on any [WidgetState] by diff --git a/packages/material_ui/lib/src/search_anchor.dart b/packages/material_ui/lib/src/search_anchor.dart index d7173130305f..c4cc7522ea90 100644 --- a/packages/material_ui/lib/src/search_anchor.dart +++ b/packages/material_ui/lib/src/search_anchor.dart @@ -86,44 +86,56 @@ typedef ViewBuilder = Widget Function(Iterable suggestions); /// is in full-screen mode, changing the window size, such as rotating a mobile /// device from portrait mode to landscape mode, will not close the search view. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to use an IconButton to open a search view in a [SearchAnchor]. /// It also shows how to use [SearchController] to open or close the search view route. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/search_anchor/search_anchor.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to set up a floating (or pinned) AppBar with a /// [SearchAnchor] for a title. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/search_anchor/search_anchor.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to fetch the search suggestions from a remote API. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/search_anchor/search_anchor.3.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example demonstrates fetching the search suggestions asynchronously and /// debouncing network calls. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/search_anchor/search_anchor.4.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -174,15 +186,18 @@ class SearchAnchor extends StatefulWidget { /// All the barX parameters are used to customize the anchor. Similarly, all the /// viewX parameters are used to override the view's defaults. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows how to use a [SearchAnchor.bar] which uses a default search /// bar to open a search view route. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/search_anchor/search_anchor.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// factory SearchAnchor.bar({ Widget? barLeading, Iterable? barTrailing, @@ -1402,16 +1417,19 @@ class SearchController extends TextEditingController { /// These actions can represent additional modes of searching (like voice search), /// a separate high-level action (such as current location) or an overflow menu. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example demonstrates how to use a [SearchBar] as the return value of the /// [SearchAnchor.builder] property. The [SearchBar] also includes a leading search /// icon and a trailing action to toggle the brightness. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/search_anchor/search_bar.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/segmented_button.dart b/packages/material_ui/lib/src/segmented_button.dart index 1ca049304d7b..72e07c7f0231 100644 --- a/packages/material_ui/lib/src/segmented_button.dart +++ b/packages/material_ui/lib/src/segmented_button.dart @@ -93,24 +93,30 @@ class ButtonSegment { /// then the entire segmented button will be disabled, regardless of the /// individual segment settings. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to display a [SegmentedButton] with either a single or /// multiple selection. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/segmented_button/segmented_button.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample showcases how to customize [SegmentedButton] using [SegmentedButton.styleFrom]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/segmented_button/segmented_button.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/selection_area.dart b/packages/material_ui/lib/src/selection_area.dart index c1fd841e73d1..32794841abf4 100644 --- a/packages/material_ui/lib/src/selection_area.dart +++ b/packages/material_ui/lib/src/selection_area.dart @@ -31,14 +31,17 @@ import 'theme.dart'; /// contains a [MaterialLocalizations] delegate; using the [MaterialApp] widget /// ensures that such an ancestor is present. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to make a screen selectable. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/selection_area/selection_area.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -82,15 +85,18 @@ class SelectionArea extends StatefulWidget { /// If not provided, will build a default menu based on the ambient /// [ThemeData.platform]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows how to build a custom context menu for any selected /// content in a SelectionArea. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/context_menu/selectable_region_toolbar_builder.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// See also: /// diff --git a/packages/material_ui/lib/src/slider.dart b/packages/material_ui/lib/src/slider.dart index 5d77348679f5..362999b3e71d 100644 --- a/packages/material_ui/lib/src/slider.dart +++ b/packages/material_ui/lib/src/slider.dart @@ -78,26 +78,32 @@ enum SliderInteraction { /// /// {@youtube 560 315 https://www.youtube.com/watch?v=ufb4gIPDmEs} /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example showcases non-discrete and discrete [Slider]s. /// The [Slider]s will show the updated ![Material 3 Design appearance](https://m3.material.io/components/sliders/overview) /// when setting the [Slider.year2023] flag to false. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/slider/slider.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a [Slider] widget using the [Slider.secondaryTrackValue] /// to show a secondary track in the slider. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/slider/slider.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// A slider can be used to select from either a continuous or a discrete set of /// values. The default is to use a continuous range of values from [min] to diff --git a/packages/material_ui/lib/src/snack_bar.dart b/packages/material_ui/lib/src/snack_bar.dart index 056114083885..008e1d4ad484 100644 --- a/packages/material_ui/lib/src/snack_bar.dart +++ b/packages/material_ui/lib/src/snack_bar.dart @@ -234,36 +234,45 @@ class _SnackBarActionState extends State { /// the floating action button. It also works in the case of a back gesture /// transition. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Here is an example of a [SnackBar] with an [action] button implemented using /// [SnackBarAction]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/snack_bar/snack_bar.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// Here is an example of a customized [SnackBar]. It utilizes /// [behavior], [shape], [padding], [width], and [duration] to customize the /// location, appearance, and the duration for which the [SnackBar] is visible. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/snack_bar/snack_bar.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example demonstrates the various [SnackBar] widget components, /// including an optional icon, in either floating or fixed format. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/snack_bar/snack_bar.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/stepper.dart b/packages/material_ui/lib/src/stepper.dart index ab94ee196d3e..7542669aa008 100644 --- a/packages/material_ui/lib/src/stepper.dart +++ b/packages/material_ui/lib/src/stepper.dart @@ -190,15 +190,18 @@ class Step { /// to this widget based on some logic triggered by the three callbacks that it /// provides. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// An example the shows how to use the [Stepper], and the [Stepper] UI /// appearance. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/stepper/stepper.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -302,8 +305,7 @@ class Stepper extends StatefulWidget { /// [ControlsDetails.currentStep] value within the callback can change the text /// of the continue or cancel button depending on which step users are at. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// Creates a stepper control with custom buttons. /// @@ -344,9 +346,13 @@ class Stepper extends StatefulWidget { /// ); /// } /// ``` + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/stepper/stepper.controls_builder.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final ControlsWidgetBuilder? controlsBuilder; /// The elevation of this stepper's [Material] when [type] is [StepperType.horizontal]. @@ -1047,14 +1053,17 @@ class _TrianglePainter extends CustomPainter { /// ) /// ``` /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// An example that uses [StepStyle] to customize the appearance of each [Step] in a [Stepper]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/stepper/step_style.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// @immutable class StepStyle with Diagnosticable { diff --git a/packages/material_ui/lib/src/switch.dart b/packages/material_ui/lib/src/switch.dart index 60c37e766624..fea249829c77 100644 --- a/packages/material_ui/lib/src/switch.dart +++ b/packages/material_ui/lib/src/switch.dart @@ -53,45 +53,57 @@ enum _SwitchType { material, adaptive } /// If [ThemeData.useMaterial3] is set to true, users can use [Switch.thumbIcon] /// to add optional Icons based on the different [WidgetState]s of the [Switch]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a toggleable [Switch]. When the thumb slides to the other /// side of the track, the switch is toggled between on/off. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/switch/switch.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to customize [Switch] using [WidgetStateProperty] /// switch properties. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/switch/switch.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to add icons on the thumb of the [Switch] using the /// [Switch.thumbIcon] property. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/switch/switch.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to use the ambient [CupertinoThemeData] to style all /// widgets which would otherwise use iOS defaults. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/switch/switch.3.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -166,15 +178,18 @@ class Switch extends StatelessWidget { /// where you don't want the overall [ThemeData.switchTheme] to apply when /// this adaptive constructor is used. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample shows how to create and use subclasses of [Adaptation] that /// define adaptive [SwitchThemeData]s. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/switch/switch.4.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// The target platform is based on the current [Theme]: [ThemeData.platform]. const Switch.adaptive({ diff --git a/packages/material_ui/lib/src/switch_list_tile.dart b/packages/material_ui/lib/src/switch_list_tile.dart index a061c1f4ca67..f0149a204080 100644 --- a/packages/material_ui/lib/src/switch_list_tile.dart +++ b/packages/material_ui/lib/src/switch_list_tile.dart @@ -96,27 +96,33 @@ enum _SwitchListTileType { material, adaptive } /// To show the [SwitchListTile] as disabled, pass null as the [onChanged] /// callback. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// ![SwitchListTile sample](https://flutter.github.io/assets-for-api-docs/assets/material/switch_list_tile.png) /// /// This widget shows a switch that, when toggled, changes the state of a [bool] /// member field called `_lights`. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/switch_list_tile/switch_list_tile.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample demonstrates how [SwitchListTile] positions the switch widget /// relative to the text in different configurations. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/switch_list_tile/switch_list_tile.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Semantics in SwitchListTile /// @@ -135,8 +141,7 @@ enum _SwitchListTileType { material, adaptive } /// into one. Therefore, it may be necessary to create a custom radio tile /// widget to accommodate similar use cases. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// ![Switch list tile semantics sample](https://flutter.github.io/assets-for-api-docs/assets/material/switch_list_tile_semantics.png) /// @@ -144,9 +149,13 @@ enum _SwitchListTileType { material, adaptive } /// LinkedLabelRadio, that includes an interactive [RichText] widget that /// handles tap gestures. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/switch_list_tile/custom_labeled_switch.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## SwitchListTile isn't exactly what I want /// @@ -155,17 +164,20 @@ enum _SwitchListTileType { material, adaptive } /// combining [Switch] with other widgets, such as [Text], [Padding] and /// [InkWell]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// ![Custom switch list tile sample](https://flutter.github.io/assets-for-api-docs/assets/material/switch_list_tile_custom.png) /// /// Here is an example of a custom LabeledSwitch widget, but you can easily /// make your own configurable widget. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/switch_list_tile/custom_labeled_switch.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/tab_controller.dart b/packages/material_ui/lib/src/tab_controller.dart index d9d39d2cdb6b..ac07fb49fab7 100644 --- a/packages/material_ui/lib/src/tab_controller.dart +++ b/packages/material_ui/lib/src/tab_controller.dart @@ -94,15 +94,18 @@ import 'constants.dart'; /// // TODO(framework): End of the blue example container. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to listen to page updates in [TabBar] and [TabBarView] /// when using [DefaultTabController]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/tab_controller/tab_controller.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// class TabController extends ChangeNotifier { /// Creates an object that manages the state required by [TabBar] and a diff --git a/packages/material_ui/lib/src/tabs.dart b/packages/material_ui/lib/src/tabs.dart index de3acbc6dc34..d4834929ad8e 100644 --- a/packages/material_ui/lib/src/tabs.dart +++ b/packages/material_ui/lib/src/tabs.dart @@ -950,40 +950,48 @@ typedef TabValueChanged = void Function(T value, int index); /// /// Uses values from [TabBarThemeData] if it is set in the current context. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows the implementation of [TabBar] and [TabBarView] using a [DefaultTabController]. /// Each [Tab] corresponds to a child of the [TabBarView] in the order they are written. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/tabs/tab_bar.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// [TabBar] can also be implemented by using a [TabController] which provides more options /// to control the behavior of the [TabBar] and [TabBarView]. This can be used instead of /// a [DefaultTabController], demonstrated below. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/tabs/tab_bar.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample showcases nested Material 3 [TabBar]s. It consists of a primary /// [TabBar] with nested a secondary [TabBar]. The primary [TabBar] uses a /// [DefaultTabController] while the secondary [TabBar] uses a [TabController]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/tabs/tab_bar.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample showcases how to apply custom behavior based on the scroll in [TabBar]. /// It utilizes scroll notifications ([ScrollMetricsNotification] @@ -991,9 +999,13 @@ typedef TabValueChanged = void Function(T value, int index); /// to monitor the scroll offset, allowing for interface customization /// based on the obtained offset. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/tabs/tab_bar.3.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -1062,16 +1074,19 @@ class TabBar extends StatefulWidget implements PreferredSizeWidget { /// Secondary tabs are used within a content area to further separate related /// content and establish hierarchy. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample showcases nested Material 3 [TabBar]s. It consists of a primary /// [TabBar] with nested a secondary [TabBar]. The primary [TabBar] uses a /// [DefaultTabController] while the secondary [TabBar] uses a [TabController]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/tabs/tab_bar.2.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// See also: /// @@ -1392,15 +1407,18 @@ class TabBar extends StatefulWidget implements PreferredSizeWidget { /// twice. First to represent hover exiting the initial tab, and then second /// for the pointer entering hover over the next tab. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample shows how to customize a [Tab] in response to hovering over a /// [TabBar]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/tabs/tab_bar.onHover.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final TabValueChanged? onHover; /// An optional callback that's called when a [Tab]'s focus state in the @@ -1415,15 +1433,18 @@ class TabBar extends StatefulWidget implements PreferredSizeWidget { /// twice. First to represent focus being lost by the initially focused tab, /// and then second for the next tab gaining focus. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample shows how to customize a [Tab] based on focus traversal in /// enclosing [TabBar]. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/tabs/tab_bar.onFocusChange.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final TabValueChanged? onFocusChange; /// How the [TabBar]'s scroll view should respond to user input. @@ -1511,15 +1532,18 @@ class TabBar extends StatefulWidget implements PreferredSizeWidget { /// [indicatorSize] is [TabBarIndicatorSize.tab], otherwise it will animate /// with an elastic effect if the [indicatorSize] is [TabBarIndicatorSize.label]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample shows how to customize the animation behavior of the tab indicator /// by using the [indicatorAnimation] property. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/tabs/tab_bar.indicator_animation.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// See also: /// diff --git a/packages/material_ui/lib/src/text_button.dart b/packages/material_ui/lib/src/text_button.dart index 13438a07b590..e733013c85b4 100644 --- a/packages/material_ui/lib/src/text_button.dart +++ b/packages/material_ui/lib/src/text_button.dart @@ -55,26 +55,32 @@ import 'theme_data.dart'; /// If the [onPressed] and [onLongPress] callbacks are null, then this /// button will be disabled, it will not react to touch. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows various ways to configure TextButtons, from the /// simplest default appearance to versions that don't resemble /// Material Design at all. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/text_button/text_button.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample demonstrates using the [statesController] parameter to create a button /// that adds support for [WidgetState.selected]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/text_button/text_button.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/text_field.dart b/packages/material_ui/lib/src/text_field.dart index f2af4fc6c2c8..f3397f063068 100644 --- a/packages/material_ui/lib/src/text_field.dart +++ b/packages/material_ui/lib/src/text_field.dart @@ -117,16 +117,19 @@ class _TextFieldSelectionGestureDetectorBuilder extends TextSelectionGestureDete /// /// ## Obscured Input /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to create a [TextField] that will obscure input. The /// [InputDecoration] surrounds the field in a border using [OutlineInputBorder] /// and adds a label. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/text_field/text_field.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Reading values /// @@ -134,15 +137,18 @@ class _TextFieldSelectionGestureDetectorBuilder extends TextSelectionGestureDete /// callback. This callback is applied to the text field's current value when /// the user finishes editing. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to get a value from a TextField via the [onSubmitted] /// callback. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/text_field/text_field.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// {@macro flutter.widgets.EditableText.lifeCycle} /// @@ -170,15 +176,18 @@ class _TextFieldSelectionGestureDetectorBuilder extends TextSelectionGestureDete /// /// {@macro flutter.widgets.editableText.accessibility} /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to style a text field to match a filled or outlined /// Material Design 3 text field. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/text_field/text_field.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Scrolling Considerations /// @@ -188,16 +197,19 @@ class _TextFieldSelectionGestureDetectorBuilder extends TextSelectionGestureDete /// [TextField] to ensure proper scroll coordination for [TextField] and its /// components like [TextSelectionOverlay]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample demonstrates how to use the [Shortcuts] and [Actions] widgets /// to create a custom `Shift+Enter` keyboard shortcut for inserting a new line /// in a [TextField]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/text_field/text_field.3.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// @@ -376,14 +388,17 @@ class TextField extends StatefulWidget { /// /// {@macro flutter.widgets.magnifier.intro} /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample demonstrates how to customize the magnifier that this text field uses. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/text_field/text_field_magnifier.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// final TextMagnifierConfiguration? magnifierConfiguration; /// {@macro flutter.widgets.editableText.groupId} @@ -757,8 +772,7 @@ class TextField extends StatefulWidget { /// {@macro flutter.widgets.editableText.onTapOutside} /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This example shows how to use a `TextFieldTapRegion` to wrap a set of /// "spinner" buttons that increment and decrement a value in the [TextField] @@ -767,9 +781,13 @@ class TextField extends StatefulWidget { /// This example includes a generic `SpinnerField` class that you can copy /// into your own project and customize. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/text_field/text_field_tap_region.0.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// See also: /// diff --git a/packages/material_ui/lib/src/text_form_field.dart b/packages/material_ui/lib/src/text_form_field.dart index d835c830e64c..1f477aa8a9ed 100644 --- a/packages/material_ui/lib/src/text_form_field.dart +++ b/packages/material_ui/lib/src/text_form_field.dart @@ -77,25 +77,31 @@ export 'package:flutter/services.dart' show SmartDashesType, SmartQuotesType; /// // TODO(framework): End of the blue example container. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to move the focus to the next field when the user /// presses the SPACE key. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/text_form_field/text_form_field.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how to force an error text to the field after making /// an asynchronous call. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/text_form_field/text_form_field.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/theme_data.dart b/packages/material_ui/lib/src/theme_data.dart index b2326966eeca..7df2c8625c6e 100644 --- a/packages/material_ui/lib/src/theme_data.dart +++ b/packages/material_ui/lib/src/theme_data.dart @@ -102,17 +102,20 @@ class Adaptation { /// uses an empty [SwitchThemeData] if a matching adaptation is not found, for /// the sake of backwards compatibility. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample shows how to create and use subclasses of [Adaptation] that /// define adaptive [SwitchThemeData]s. The [adapt] method in this example is /// overridden to only customize cupertino-style switches, but it can also be /// used to customize any other platforms. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/switch/switch.4.dart} /// - // TODO(framework): End of the @dartpad directive. + /// T adapt(ThemeData theme, T defaultValue) => defaultValue; } @@ -125,15 +128,18 @@ class Adaptation { /// [lerp] methods. The latter will ensure smooth transitions of properties when /// switching themes. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to create and use a subclass of [ThemeExtension] that /// defines two colors. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/theme/theme_extension.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// abstract class ThemeExtension> { /// Enable const constructor for subclasses. const ThemeExtension(); @@ -208,8 +214,7 @@ enum MaterialTapTargetSize { /// for the subtree that appears below the new [Theme], or insert a widget /// that creates a new BuildContext, like [Builder]. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example demonstrates how a typical [MaterialApp] specifies /// and uses a custom [Theme]. The theme's [ColorScheme] is based on a @@ -218,9 +223,13 @@ enum MaterialTapTargetSize { /// default configuration of [FloatingActionButton] to show how to /// customize the appearance a class of components. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/theme_data/theme_data.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See for /// more discussion on how to pick the right colors. @@ -987,15 +996,18 @@ class ThemeData with Diagnosticable { /// /// To obtain an extension, use [extension]. /// - // TODO(framework): Replace the following block with a @dartpad directive - // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// /// /// This sample shows how to create and use a subclass of [ThemeExtension] that /// defines two colors. /// + // TODO(framework): Replace the following block with a @dartpad directive + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 + /// {@macro material_ui.dartpad_guide} + /// /// {@example /example/lib/theme/theme_extension.1.dart} /// - // TODO(framework): End of the @dartpad directive. + /// /// /// See also: /// diff --git a/packages/material_ui/lib/src/time_picker.dart b/packages/material_ui/lib/src/time_picker.dart index 783e012a2bc9..cc1829517fee 100644 --- a/packages/material_ui/lib/src/time_picker.dart +++ b/packages/material_ui/lib/src/time_picker.dart @@ -3245,15 +3245,18 @@ class _TimePickerState extends State<_TimePicker> with RestorationMixin { /// // TODO(framework): End of the blue example container. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example illustrates how to open a time picker, and allows exploring /// some of the variations in the types of time pickers that may be shown. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/time_picker/show_time_picker.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: /// diff --git a/packages/material_ui/lib/src/toggle_buttons.dart b/packages/material_ui/lib/src/toggle_buttons.dart index c020ec7f7610..6ee275ce63ad 100644 --- a/packages/material_ui/lib/src/toggle_buttons.dart +++ b/packages/material_ui/lib/src/toggle_buttons.dart @@ -57,24 +57,30 @@ import 'toggle_buttons_theme.dart'; /// The [SegmentedButton.style] is a [ButtonStyle] style field, which can be /// used to customize the entire segmented button and the individual segments. /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This sample shows how to migrate [ToggleButtons] that allows multiple /// or no selection to [SegmentedButton] that allows multiple or no selection. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/toggle_buttons/toggle_buttons.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example showcase [ToggleButtons] in various configurations. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/toggle_buttons/toggle_buttons.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// ## Customizing toggle buttons /// Each toggle's behavior can be configured by the [onPressed] callback, which diff --git a/packages/material_ui/lib/src/tooltip.dart b/packages/material_ui/lib/src/tooltip.dart index afbb80d7cb44..bcdd339386ae 100644 --- a/packages/material_ui/lib/src/tooltip.dart +++ b/packages/material_ui/lib/src/tooltip.dart @@ -37,8 +37,7 @@ import 'tooltip_visibility.dart'; /// /// {@youtube 560 315 https://www.youtube.com/watch?v=EeEfD5fI-5Q} /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example show a basic [Tooltip] which has a [Text] as child. /// [message] contains your label to be shown by the tooltip when @@ -56,12 +55,15 @@ import 'tooltip_visibility.dart'; /// /// or it can be set directly on each tooltip with [Tooltip.preferBelow]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/tooltip/tooltip.0.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example covers most of the attributes available in Tooltip. /// `decoration` has been used to give a gradient and borderRadius to Tooltip. @@ -75,31 +77,41 @@ import 'tooltip_visibility.dart'; /// `waitDuration` accepts a Duration for which a mouse pointer has to hover over the child /// widget before the tooltip is shown. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/tooltip/tooltip.1.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows a rich [Tooltip] that specifies the [richMessage] /// parameter instead of the [message] parameter (only one of these may be /// non-null. Any [InlineSpan] can be specified for the [richMessage] attribute, /// including [WidgetSpan]. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/tooltip/tooltip.2.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// -// TODO(framework): Replace the following block with a @dartpad directive -// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// /// /// This example shows how [Tooltip] can be shown manually with [TooltipTriggerMode.manual] /// by calling the [TooltipState.ensureTooltipVisible] function. /// +// TODO(framework): Replace the following block with a @dartpad directive +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123 +/// {@macro material_ui.dartpad_guide} +/// /// {@example /example/lib/tooltip/tooltip.3.dart} /// -// TODO(framework): End of the @dartpad directive. +/// /// /// See also: ///