diff --git a/analysis_options.yaml b/analysis_options.yaml index 212c3e2fd157..daadedd6d5fb 100644 --- a/analysis_options.yaml +++ b/analysis_options.yaml @@ -16,6 +16,9 @@ analyzer: # something (https://github.com/flutter/flutter/issues/143312) deprecated_member_use: ignore deprecated_member_use_from_same_package: ignore + # `dart analyze` hasn't recognized the @example directive yet. + # Remove it once https://github.com/dart-lang/sdk/pull/63646 is landed. + doc_directive_unknown: ignore exclude: # DIFFERENT FROM FLUTTER/FLUTTER # Ignore generated files - '**/*.pb.dart' diff --git a/packages/cupertino_ui/example/analysis_options.yaml b/packages/cupertino_ui/example/analysis_options.yaml index 561497259820..16500c69a9ca 100644 --- a/packages/cupertino_ui/example/analysis_options.yaml +++ b/packages/cupertino_ui/example/analysis_options.yaml @@ -1,5 +1,3 @@ -# This file is also used by dev/bots/analyze_snippet_code.dart to analyze code snippets (`{@tool snippet}` sections). - # The following line activates a set of recommended lints for Flutter apps, # packages, and plugins designed to encourage good coding practices. analyzer: diff --git a/packages/cupertino_ui/lib/src/activity_indicator.dart b/packages/cupertino_ui/lib/src/activity_indicator.dart index 14d213227705..e4e2ff138070 100644 --- a/packages/cupertino_ui/lib/src/activity_indicator.dart +++ b/packages/cupertino_ui/lib/src/activity_indicator.dart @@ -21,11 +21,14 @@ const Color _kActiveTickColor = CupertinoDynamicColor.withBrightness( /// /// {@youtube 560 315 https://www.youtube.com/watch?v=AENVH-ZqKDQ} /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/activity_indicator/cupertino_activity_indicator.0.dart ** -/// {@end-tool} +/// {@example /example/lib/activity_indicator/cupertino_activity_indicator.0.dart} +/// +// TODO(framework): End of the @dartpad directive. /// /// See also: /// @@ -201,11 +204,14 @@ class _CupertinoActivityIndicatorPainter extends CustomPainter { /// The [CupertinoLinearActivityIndicator] is a linear progress bar that /// displays a colored bar to indicate the progress of an ongoing task. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/activity_indicator/cupertino_linear_activity_indicator.0.dart ** -/// {@end-tool} +/// {@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/app.dart b/packages/cupertino_ui/lib/src/app.dart index 91591a598b1a..a3cb84be1af2 100644 --- a/packages/cupertino_ui/lib/src/app.dart +++ b/packages/cupertino_ui/lib/src/app.dart @@ -67,7 +67,11 @@ import 'theme.dart'; /// * The San Francisco font family is unavailable on Android and can result /// in undefined font behavior. /// -/// {@tool snippet} +// TODO(framework): Replace the following block with a blue example container +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 +// TODO(framework): Add unit tests to this code snippet. +// https://github.com/flutter/flutter/issues/188530 +/// /// This example shows how to create a [CupertinoApp] that disables the "debug" /// banner with a [home] route that will be displayed when the app is launched. /// @@ -84,9 +88,14 @@ import 'theme.dart'; /// debugShowCheckedModeBanner: false, /// ) /// ``` -/// {@end-tool} /// -/// {@tool snippet} +// TODO(framework): End of the blue example container. +/// +// TODO(framework): Replace the following block with a blue example container +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 +// TODO(framework): Add unit tests to this code snippet. +// https://github.com/flutter/flutter/issues/188530 +/// /// This example shows how to create a [CupertinoApp] that uses the [routes] /// `Map` to define the "home" route and an "about" route. /// @@ -112,9 +121,14 @@ import 'theme.dart'; /// }, /// ) /// ``` -/// {@end-tool} /// -/// {@tool snippet} +// TODO(framework): End of the blue example container. +/// +// TODO(framework): Replace the following block with a blue example container +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 +// TODO(framework): Add unit tests to this code snippet. +// https://github.com/flutter/flutter/issues/188530 +/// /// This example shows how to create a [CupertinoApp] that defines a [theme] that /// will be used for Cupertino widgets in the app. /// @@ -134,7 +148,8 @@ import 'theme.dart'; /// ), /// ) /// ``` -/// {@end-tool} +/// +// TODO(framework): End of the blue example container. /// /// See also: /// @@ -357,7 +372,11 @@ class CupertinoApp extends StatefulWidget { final bool debugShowCheckedModeBanner; /// {@macro flutter.widgets.widgetsApp.shortcuts} - /// {@tool snippet} + // TODO(framework): Replace the following block with a blue example container + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 + // TODO(framework): Add unit tests to this code snippet. + // https://github.com/flutter/flutter/issues/188530 + /// /// This example shows how to add a single shortcut for /// [LogicalKeyboardKey.select] to the default shortcuts without needing to /// add your own [Shortcuts] widget. @@ -380,12 +399,17 @@ class CupertinoApp extends StatefulWidget { /// ); /// } /// ``` - /// {@end-tool} + /// + // TODO(framework): End of the blue example container. /// {@macro flutter.widgets.widgetsApp.shortcuts.seeAlso} final Map? shortcuts; /// {@macro flutter.widgets.widgetsApp.actions} - /// {@tool snippet} + // TODO(framework): Replace the following block with a blue example container + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 + // TODO(framework): Add unit tests to this code snippet. + // https://github.com/flutter/flutter/issues/188530 + /// /// This example shows how to add a single action handling an /// [ActivateAction] to the default actions without needing to /// add your own [Actions] widget. @@ -413,7 +437,8 @@ class CupertinoApp extends StatefulWidget { /// ); /// } /// ``` - /// {@end-tool} + /// + // TODO(framework): End of the blue example container. /// {@macro flutter.widgets.widgetsApp.actions.seeAlso} final Map>? actions; diff --git a/packages/cupertino_ui/lib/src/bottom_tab_bar.dart b/packages/cupertino_ui/lib/src/bottom_tab_bar.dart index 91216def0cc6..aef0f1ac0516 100644 --- a/packages/cupertino_ui/lib/src/bottom_tab_bar.dart +++ b/packages/cupertino_ui/lib/src/bottom_tab_bar.dart @@ -46,11 +46,14 @@ const Color _kDefaultTabBarInactiveColor = CupertinoColors.inactiveGray; /// this behavior, wrap each of the `navigationBar`'s components inside a /// [MediaQuery] with the desired [TextScaler]. /// -/// {@tool dartpad} +// 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]. /// -/// ** See code in examples/api/lib/cupertino/bottom_tab_bar/cupertino_tab_bar.0.dart ** -/// {@end-tool} +/// {@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 f87df8c1d6fd..8b4d02a5c5fe 100644 --- a/packages/cupertino_ui/lib/src/button.dart +++ b/packages/cupertino_ui/lib/src/button.dart @@ -58,12 +58,15 @@ enum _CupertinoButtonStyle { /// with the [CupertinoThemeData.primaryColor] (or /// [CupertinoThemeData.primaryContrastingColor] if the button is disabled). /// -/// {@tool dartpad} +// 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]. /// -/// ** See code in examples/api/lib/cupertino/button/cupertino_button.0.dart ** -/// {@end-tool} +/// {@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 7feb65121fa9..c917fdb4aece 100644 --- a/packages/cupertino_ui/lib/src/checkbox.dart +++ b/packages/cupertino_ui/lib/src/checkbox.dart @@ -73,11 +73,14 @@ const List _kDisabledDarkGradientOpacities = [0.08, 0.14]; /// [kMinInteractiveDimensionCupertino] pixels to meet accessibility /// guidelines. /// -/// {@tool dartpad} +// 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]. /// -/// ** See code in examples/api/lib/cupertino/checkbox/cupertino_checkbox.0.dart ** -/// {@end-tool} +/// {@example /example/lib/checkbox/cupertino_checkbox.0.dart} +/// +// TODO(framework): End of the @dartpad directive. /// /// See also: /// @@ -202,7 +205,11 @@ class CupertinoCheckbox extends StatefulWidget { /// * [WidgetState.focused]. /// * [WidgetState.disabled]. /// - /// {@tool snippet} + // TODO(framework): Replace the following block with a blue example container + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 + // TODO(framework): Add unit tests to this code snippet. + // https://github.com/flutter/flutter/issues/188530 + /// /// This example resolves the [fillColor] based on the current [WidgetState] /// of the [CupertinoCheckbox], providing a different [Color] when it is /// [WidgetState.disabled]. @@ -219,7 +226,8 @@ class CupertinoCheckbox extends StatefulWidget { /// }) /// ) /// ``` - /// {@end-tool} + /// + // TODO(framework): End of the blue example container. /// {@endtemplate} /// /// If [fillColor] resolves to null for the requested state, then the fill color diff --git a/packages/cupertino_ui/lib/src/colors.dart b/packages/cupertino_ui/lib/src/colors.dart index 2c93f5559e48..a82cb600b426 100644 --- a/packages/cupertino_ui/lib/src/colors.dart +++ b/packages/cupertino_ui/lib/src/colors.dart @@ -661,7 +661,11 @@ abstract final class CupertinoColors { /// [CupertinoDynamicColor.resolve] against its own [BuildContext], on a best-effort /// basis. /// -/// {@tool snippet} +// TODO(framework): Replace the following block with a blue example container +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 +// TODO(framework): Add unit tests to this code snippet. +// https://github.com/flutter/flutter/issues/188530 +/// /// By default a [CupertinoButton] has no background color. The following sample /// code shows how to build a [CupertinoButton] that appears white in light mode, /// and changes automatically to black in dark mode. @@ -677,7 +681,8 @@ abstract final class CupertinoColors { /// child: child, /// ) /// ``` -/// {@end-tool} +/// +// TODO(framework): End of the blue example container. /// /// ### Using a [CupertinoDynamicColor] from a [CupertinoTheme] /// @@ -686,7 +691,11 @@ abstract final class CupertinoColors { /// implicitly resolves all the colors used in the retrieved [CupertinoThemeData], /// before returning it. /// -/// {@tool snippet} +// TODO(framework): Replace the following block with a blue example container +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 +// TODO(framework): Add unit tests to this code snippet. +// https://github.com/flutter/flutter/issues/188530 +/// /// The following code sample creates a [Container] with the `primaryColor` of the /// current theme. If `primaryColor` is a [CupertinoDynamicColor], the container /// will be adaptive, thanks to [CupertinoTheme.of]: it will switch to `primaryColor`'s @@ -701,7 +710,8 @@ abstract final class CupertinoColors { /// color: CupertinoTheme.of(context).primaryColor, /// ) /// ``` -/// {@end-tool} +/// +// TODO(framework): End of the blue example container. /// /// ### Manually Resolving a [CupertinoDynamicColor] /// @@ -712,7 +722,11 @@ abstract final class CupertinoColors { /// the colors used in the [Border] have to be resolved manually before being passed /// to [CupertinoNavigationBar]'s constructor. /// -/// {@tool snippet} +// TODO(framework): Replace the following block with a blue example container +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 +// TODO(framework): Add unit tests to this code snippet. +// https://github.com/flutter/flutter/issues/188530 +/// /// /// The following code samples demonstrate two cases where you have to manually /// resolve a [CupertinoDynamicColor]. @@ -735,7 +749,8 @@ abstract final class CupertinoColors { /// color: CupertinoDynamicColor.resolve(CupertinoColors.systemBlue, context), /// ) /// ``` -/// {@end-tool} +/// +// TODO(framework): End of the blue example container. /// /// See also: /// diff --git a/packages/cupertino_ui/lib/src/context_menu.dart b/packages/cupertino_ui/lib/src/context_menu.dart index e8e15af266a6..72e87b3b0212 100644 --- a/packages/cupertino_ui/lib/src/context_menu.dart +++ b/packages/cupertino_ui/lib/src/context_menu.dart @@ -96,19 +96,25 @@ enum _ContextMenuLocation { center, left, right } /// background or by calling `Navigator.pop(context)`. Unlike [PopupRoute], it can /// also be closed by swiping downwards. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/context_menu/cupertino_context_menu.0.dart ** -/// {@end-tool} +/// {@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 /// -/// {@tool dartpad} /// This sample shows a similar CupertinoContextMenu, this time using [builder] /// to add a border radius to the widget. /// -/// ** See code in examples/api/lib/cupertino/context_menu/cupertino_context_menu.1.dart ** -/// {@end-tool} +/// {@example /example/lib/context_menu/cupertino_context_menu.1.dart} +/// +// TODO(framework): End of the @dartpad directive. /// /// See also: /// @@ -142,7 +148,11 @@ class CupertinoContextMenu extends StatefulWidget { /// Exposes the default border radius for matching iOS 16.0 behavior. This /// value was eyeballed from the iOS simulator running iOS 16.0. /// - /// {@tool snippet} + // TODO(framework): Replace the following block with a blue example container + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 + // TODO(framework): Add unit tests to this code snippet. + // https://github.com/flutter/flutter/issues/188530 + /// /// /// Below is example code in order to match the default border radius for an /// iOS 16.0 open preview. @@ -205,7 +215,8 @@ class CupertinoContextMenu extends StatefulWidget { /// ) /// ``` /// - /// {@end-tool} + /// + // TODO(framework): End of the blue example container. static const double kOpenBorderRadius = _previewBorderRadiusRatio; /// Exposes the final box shadow of the opening animation of the child widget @@ -248,7 +259,11 @@ class CupertinoContextMenu extends StatefulWidget { /// the widget from 0 to [animationOpensAt], and the second stage for when the /// widget fully opens up to the menu, from [animationOpensAt] to 1. /// - /// {@tool snippet} + // TODO(framework): Replace the following block with a blue example container + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 + // TODO(framework): Add unit tests to this code snippet. + // https://github.com/flutter/flutter/issues/188530 + /// /// /// Below is an example of using [builder] to show an image tile setup to be /// opened in the default way to match a native iOS 16.0 app. The behavior @@ -314,9 +329,12 @@ class CupertinoContextMenu extends StatefulWidget { /// ) /// ``` /// - /// {@end-tool} /// - /// {@tool dartpad} + // 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]. /// /// If a widget is passed to the [child] parameter with properties that @@ -327,8 +345,9 @@ class CupertinoContextMenu extends StatefulWidget { /// like [CupertinoContextMenu.kEndBoxShadow], to match the native iOS /// animation as close as desired. /// - /// ** See code in examples/api/lib/cupertino/context_menu/cupertino_context_menu.1.dart ** - /// {@end-tool} + /// {@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 073221be2577..bac359f2a314 100644 --- a/packages/cupertino_ui/lib/src/date_picker.dart +++ b/packages/cupertino_ui/lib/src/date_picker.dart @@ -230,15 +230,18 @@ enum _PickerColumnType { /// full screen width. Content texts are shown with /// [CupertinoTextThemeData.dateTimePickerTextStyle]. /// -/// {@tool dartpad} +// 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 /// the drag the date or time wheels, the picker will call onDateTimeChanged callback. /// /// CupertinoDatePicker can be displayed directly on a screen or in a popup. /// -/// ** See code in examples/api/lib/cupertino/date_picker/cupertino_date_picker.0.dart ** -/// {@end-tool} +/// {@example /example/lib/date_picker/cupertino_date_picker.0.dart} +/// +// TODO(framework): End of the @dartpad directive. /// /// See also: /// @@ -480,7 +483,11 @@ class CupertinoDatePicker extends StatefulWidget { /// /// If the selection overlay builder returns null, no overlay will be drawn. /// - /// {@tool snippet} + // TODO(framework): Replace the following block with a blue example container + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 + // TODO(framework): Add unit tests to this code snippet. + // https://github.com/flutter/flutter/issues/188530 + /// /// /// This example shows how to recreate the default selection overlay /// with selectionOverlayBuilder. @@ -511,7 +518,8 @@ class CupertinoDatePicker extends StatefulWidget { /// }, /// ) /// ``` - /// {@end-tool} + /// + // TODO(framework): End of the blue example container. final SelectionOverlayBuilder? selectionOverlayBuilder; /// The behavior of reporting the selected date. @@ -2165,11 +2173,14 @@ enum CupertinoTimerPickerMode { /// provides more space than it needs, the picker will position itself according /// to its [alignment] property. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/date_picker/cupertino_timer_picker.0.dart ** -/// {@end-tool} +/// {@example /example/lib/date_picker/cupertino_timer_picker.0.dart} +/// +// TODO(framework): End of the @dartpad directive. /// /// See also: /// @@ -2256,7 +2267,11 @@ class CupertinoTimerPicker extends StatefulWidget { /// /// If the selection overlay builder returns null, no overlay will be drawn. /// - /// {@tool snippet} + // TODO(framework): Replace the following block with a blue example container + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 + // TODO(framework): Add unit tests to this code snippet. + // https://github.com/flutter/flutter/issues/188530 + /// /// /// This example shows how to recreate the default selection overlay /// with selectionOverlayBuilder. @@ -2285,7 +2300,8 @@ class CupertinoTimerPicker extends StatefulWidget { /// }, /// ) /// ``` - /// {@end-tool} + /// + // TODO(framework): End of the blue example container. final SelectionOverlayBuilder? selectionOverlayBuilder; /// The behavior of reporting the selected duration. diff --git a/packages/cupertino_ui/lib/src/dialog.dart b/packages/cupertino_ui/lib/src/dialog.dart index fd7bc8b1f9e7..27f79c4d7c9d 100644 --- a/packages/cupertino_ui/lib/src/dialog.dart +++ b/packages/cupertino_ui/lib/src/dialog.dart @@ -213,13 +213,16 @@ bool _isInAccessibilityMode(BuildContext context) { /// Typically passed as the child widget to [showDialog], which displays the /// dialog. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/dialog/cupertino_alert_dialog.0.dart ** -/// {@end-tool} +/// {@example /example/lib/dialog/cupertino_alert_dialog.0.dart} +/// +// TODO(framework): End of the @dartpad directive. /// /// See also: /// @@ -517,13 +520,16 @@ class _CupertinoAlertDialogState extends State { /// which is useful for more complicated layouts, such as rendering divider gaps /// in [CupertinoAlertDialog] or rendering custom surface colors. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/dialog/cupertino_popup_surface.0.dart ** -/// {@end-tool} +/// {@example /example/lib/dialog/cupertino_popup_surface.0.dart} +/// +// TODO(framework): End of the @dartpad directive. /// /// See also: /// @@ -882,7 +888,7 @@ abstract class _SlideTarget { // Recognizes sliding taps and thereupon interacts with // `_SlideTarget`s. // -// TODO(dkwingsmt): It should recompute hit testing when the app is updated, +// TODO(framework): It should recompute hit testing when the app is updated, // or better, share code with `MouseTracker`. // https://github.com/flutter/flutter/issues/155266 class _TargetSelectionGestureRecognizer extends GestureRecognizer { @@ -1052,13 +1058,16 @@ class _ActionSheetGestureDetector extends StatelessWidget { /// [showCupertinoModalPopup], which displays the action sheet by sliding it up /// from the bottom of the screen. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/dialog/cupertino_action_sheet.0.dart ** -/// {@end-tool} +/// {@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 14e06f10c8ea..162d76621d61 100644 --- a/packages/cupertino_ui/lib/src/expansion_tile.dart +++ b/packages/cupertino_ui/lib/src/expansion_tile.dart @@ -59,11 +59,14 @@ enum ExpansionTileTransitionMode { /// A single-line [CupertinoListTile] with an expansion arrow icon that expands /// or collapses the tile to reveal or hide the [child]. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/expansion_tile/cupertino_expansion_tile.0.dart ** -/// {@end-tool} +/// {@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 1257a8c984fd..33e90d360ca9 100644 --- a/packages/cupertino_ui/lib/src/form_row.dart +++ b/packages/cupertino_ui/lib/src/form_row.dart @@ -36,12 +36,15 @@ const EdgeInsetsGeometry _kDefaultPadding = EdgeInsetsDirectional.fromSTEB(20.0, /// be shown in [CupertinoColors.destructiveRed] coloring and /// medium-weighted font. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/form_row/cupertino_form_row.0.dart ** -/// {@end-tool} +/// {@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/icons.dart b/packages/cupertino_ui/lib/src/icons.dart index 1306f0de868f..4a973f70f80d 100644 --- a/packages/cupertino_ui/lib/src/icons.dart +++ b/packages/cupertino_ui/lib/src/icons.dart @@ -21,7 +21,11 @@ import 'package:flutter/widgets.dart'; /// cupertino_icons: ^1.0.0 /// ``` /// -/// {@tool snippet} +// TODO(framework): Replace the following block with a blue example container +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 +// TODO(framework): Add unit tests to this code snippet. +// https://github.com/flutter/flutter/issues/188530 +/// /// /// This example shows how to create a [Row] of Cupertino [Icon]s in different colors and /// sizes. The first [Icon] uses a [Icon.semanticLabel] to announce in accessibility @@ -52,7 +56,8 @@ import 'package:flutter/widgets.dart'; /// ], /// ) /// ``` -/// {@end-tool} +/// +// TODO(framework): End of the blue example container. /// /// For versions 0.1.3 and below, see this [glyph map](https://raw.githubusercontent.com/flutter/packages/main/third_party/packages/cupertino_icons/map.png). /// diff --git a/packages/cupertino_ui/lib/src/list_section.dart b/packages/cupertino_ui/lib/src/list_section.dart index 14f75fd85947..58283edfdf05 100644 --- a/packages/cupertino_ui/lib/src/list_section.dart +++ b/packages/cupertino_ui/lib/src/list_section.dart @@ -161,20 +161,26 @@ enum CupertinoListSectionType { /// /// {@macro flutter.material.Material.clipBehavior} /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/list_section/list_section_base.0.dart ** -/// {@end-tool} +/// {@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 /// -/// {@tool dartpad} /// Creates an "Inset Grouped" [CupertinoListSection] containing /// notched [CupertinoListTile]s with `leading`, `title`, `additionalInfo` and /// `trailing` widgets. /// -/// ** See code in examples/api/lib/cupertino/list_section/list_section_inset.0.dart ** -/// {@end-tool} +/// {@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 2b726e1de294..060ca933b1a0 100644 --- a/packages/cupertino_ui/lib/src/list_tile.dart +++ b/packages/cupertino_ui/lib/src/list_tile.dart @@ -78,12 +78,15 @@ enum _CupertinoListTileType { base, notched } /// behavior it should not be used for example to toggle the [CupertinoSwitch] /// in the trailing widget. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/list_tile/cupertino_list_tile.0.dart ** -/// {@end-tool} +/// {@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/magnifier.dart b/packages/cupertino_ui/lib/src/magnifier.dart index 322aeaaaffa7..16fbaf427dc0 100644 --- a/packages/cupertino_ui/lib/src/magnifier.dart +++ b/packages/cupertino_ui/lib/src/magnifier.dart @@ -14,11 +14,16 @@ import 'theme.dart'; /// A [CupertinoMagnifier] used for magnifying text in cases where a user's /// finger may be blocking the point of interest, like a selection handle. /// -/// {@tool dartpad} +// TODO(framework): Replace the following block with a blue example container +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 +// TODO(framework): Add unit tests to this code snippet. +// https://github.com/flutter/flutter/issues/188530 +/// /// This sample demonstrates how to use [CupertinoTextMagnifier]. /// -/// ** See code in examples/api/lib/widgets/magnifier/cupertino_text_magnifier.0.dart ** -/// {@end-tool} +/// {@example example/lib/magnifier/cupertino_text_magnifier.0.dart} +/// +// TODO(framework): End of the blue example container. /// /// Delegates styling to [CupertinoMagnifier] with its position depending on /// [magnifierInfo]. @@ -221,11 +226,16 @@ class _CupertinoTextMagnifierState extends State /// A [RawMagnifier] used for magnifying text in cases where a user's /// finger may be blocking the point of interest, like a selection handle. /// -/// {@tool dartpad} +// TODO(framework): Replace the following block with a blue example container +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 +// TODO(framework): Add unit tests to this code snippet. +// https://github.com/flutter/flutter/issues/188530 +/// /// This sample demonstrates how to use [CupertinoMagnifier]. /// -/// ** See code in examples/api/lib/widgets/magnifier/cupertino_magnifier.0.dart ** -/// {@end-tool} +/// {@example example/lib/magnifier/cupertino_magnifier.0.dart} +/// +// TODO(framework): End of the blue example container. /// /// [CupertinoMagnifier] is a wrapper around [RawMagnifier] that handles styling /// and transitions. diff --git a/packages/cupertino_ui/lib/src/menu_anchor.dart b/packages/cupertino_ui/lib/src/menu_anchor.dart index 1a99b5c4c397..762861815e0c 100644 --- a/packages/cupertino_ui/lib/src/menu_anchor.dart +++ b/packages/cupertino_ui/lib/src/menu_anchor.dart @@ -295,19 +295,25 @@ typedef CupertinoMenuAnimationStatusChangedCallback = void Function(AnimationSta /// invoked every time the [AnimationStatus] of the menu animation changes. /// /// ## Usage -/// {@tool sample} +// TODO(framework): Replace the following block with a blue example container +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 +/// /// This example demonstrates a simple [CupertinoMenuAnchor] that wraps /// a button. /// -/// ** See code in examples/api/lib/cupertino/menu_anchor/menu_anchor.0.dart ** -/// {@end-tool} +/// {@example /example/lib/menu_anchor/menu_anchor.0.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 /// -/// {@tool dartpad} /// This example demonstrates a [CupertinoMenuAnchor] that wraps a button and /// shows a menu with three [CupertinoMenuItem]s and one [CupertinoMenuDivider]. /// -/// ** See code in examples/api/lib/cupertino/menu_anchor/menu_anchor.1.dart ** -/// {@end-tool} +/// {@example /example/lib/menu_anchor/menu_anchor.1.dart} +/// +// TODO(framework): End of the @dartpad directive. /// /// See also: /// @@ -1695,19 +1701,25 @@ class _CupertinoDividerPainter extends CustomPainter { /// will perform a destructive action, and will color the text of the menu item /// [CupertinoColors.systemRed]. /// -/// {@tool sample} +// TODO(framework): Replace the following block with a blue example container +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 +/// /// This example demonstrates a simple [CupertinoMenuAnchor] that wraps /// a button. /// -/// ** See code in examples/api/lib/cupertino/menu_anchor/menu_anchor.0.dart ** -/// {@end-tool} +/// {@example /example/lib/menu_anchor/menu_anchor.0.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 /// -/// {@tool dartpad} /// This example demonstrates a [CupertinoMenuAnchor] that wraps a button and /// shows a menu with three [CupertinoMenuItem]s and one [CupertinoMenuDivider]. /// -/// ** See code in examples/api/lib/cupertino/menu_anchor/menu_anchor.1.dart ** -/// {@end-tool} +/// {@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 4bc4175aa04a..85e8acd084f2 100644 --- a/packages/cupertino_ui/lib/src/nav_bar.dart +++ b/packages/cupertino_ui/lib/src/nav_bar.dart @@ -330,21 +330,27 @@ bool _isTransitionable(BuildContext context) { /// this behavior, wrap each of the `navigationBar`'s components inside a /// [MediaQuery] with the desired [TextScaler]. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/nav_bar/cupertino_navigation_bar.0.dart ** -/// {@end-tool} +/// {@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 /// -/// {@tool dartpad} /// This example shows the resulting layout from [CupertinoNavigationBar.large] /// constructor, showing a large title similar to the expanded state of /// [CupertinoSliverNavigationBar]. /// -/// ** See code in examples/api/lib/cupertino/nav_bar/cupertino_navigation_bar.2.dart ** -/// {@end-tool} +/// {@example /example/lib/nav_bar/cupertino_navigation_bar.2.dart} +/// +// TODO(framework): End of the @dartpad directive. /// /// See also: /// @@ -620,12 +626,15 @@ class CupertinoNavigationBar extends StatefulWidget implements ObstructingPrefer /// Only widgets that implement [PreferredSizeWidget] can be used at the /// bottom of a navigation bar. /// - /// {@tool dartpad} + // 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]. /// - /// ** See code in examples/api/lib/cupertino/nav_bar/cupertino_navigation_bar.1.dart ** - /// {@end-tool} + /// {@example /example/lib/nav_bar/cupertino_navigation_bar.1.dart} + /// + // TODO(framework): End of the @dartpad directive. /// /// See also: /// @@ -926,17 +935,23 @@ 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`. /// -/// {@tool dartpad} +// 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]. /// -/// ** See code in examples/api/lib/cupertino/nav_bar/cupertino_sliver_nav_bar.0.dart ** -/// {@end-tool} +/// {@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 /// -/// {@tool dartpad} /// To add a widget to the bottom of the nav bar, wrap it with [PreferredSize] and provide its fully extended size. /// -/// ** See code in examples/api/lib/cupertino/nav_bar/cupertino_sliver_nav_bar.2.dart ** -/// {@end-tool} +/// {@example /example/lib/nav_bar/cupertino_sliver_nav_bar.2.dart} +/// +// TODO(framework): End of the @dartpad directive. /// /// See also: /// @@ -1000,12 +1015,15 @@ class CupertinoSliverNavigationBar extends StatefulWidget { /// If [automaticallyImplyTitle] is false, then the [largeTitle] argument is /// required. /// - /// {@tool dartpad} + // 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. /// - /// ** See code in examples/api/lib/cupertino/nav_bar/cupertino_sliver_nav_bar.1.dart ** - /// {@end-tool} + /// {@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 02e6fc9244db..0c844fb5dbd4 100644 --- a/packages/cupertino_ui/lib/src/page_scaffold.dart +++ b/packages/cupertino_ui/lib/src/page_scaffold.dart @@ -25,13 +25,16 @@ import 'theme.dart'; /// encloses the [ScrollView]. The [ScrollView.primary] flag is used to connect /// a [ScrollView] to the enclosing [PrimaryScrollController]. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/page_scaffold/cupertino_page_scaffold.0.dart ** -/// {@end-tool} +/// {@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 73e876af3118..2baccf0f3e38 100644 --- a/packages/cupertino_ui/lib/src/picker.dart +++ b/packages/cupertino_ui/lib/src/picker.dart @@ -50,12 +50,15 @@ const Curve _kCupertinoPickerTapToScrollCurve = Curves.easeInOut; /// /// By default, descendent texts are shown with [CupertinoTextThemeData.pickerTextStyle]. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/picker/cupertino_picker.0.dart ** -/// {@end-tool} +/// {@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 02ef7a9bee8c..fc4cc59b9685 100644 --- a/packages/cupertino_ui/lib/src/radio.dart +++ b/packages/cupertino_ui/lib/src/radio.dart @@ -70,7 +70,9 @@ const List _kDisabledDarkGradientOpacities = [0.08, 0.14]; /// [RadioGroup.groupValue], and the [CupertinoRadio] under it with matching /// [value] will be selected. /// -/// {@tool dartpad} +// 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. /// /// The currently selected character is passed into `RadioGroup.groupValue`, which is @@ -83,8 +85,9 @@ 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. /// -/// ** See code in examples/api/lib/cupertino/radio/cupertino_radio.0.dart ** -/// {@end-tool} +/// {@example /example/lib/radio/cupertino_radio.0.dart} +/// +// TODO(framework): End of the @dartpad directive. /// /// See also: /// @@ -174,12 +177,15 @@ class CupertinoRadio extends StatefulWidget { /// {@macro flutter.widget.RawRadio.toggleable} /// - /// {@tool dartpad} + // 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. /// - /// ** See code in examples/api/lib/cupertino/radio/cupertino_radio.toggleable.0.dart ** - /// {@end-tool} + /// {@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 333e52cf8cd1..e046f0687211 100644 --- a/packages/cupertino_ui/lib/src/refresh.dart +++ b/packages/cupertino_ui/lib/src/refresh.dart @@ -266,13 +266,16 @@ typedef RefreshCallback = Future Function(); /// sliver such as [CupertinoSliverNavigationBar] and your main scrollable /// content's sliver. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/refresh/cupertino_sliver_refresh_control.0.dart ** -/// {@end-tool} +/// {@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 9469628230c7..0baf10285d03 100644 --- a/packages/cupertino_ui/lib/src/route.dart +++ b/packages/cupertino_ui/lib/src/route.dart @@ -1294,7 +1294,9 @@ class CupertinoModalPopupRoute extends PopupRoute { /// /// For more information about state restoration, see [RestorationManager]. /// -/// {@tool dartpad} +// 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 /// [CupertinoApp.restorationScopeId] and using [Navigator.restorablePush] to @@ -1302,8 +1304,9 @@ class CupertinoModalPopupRoute extends PopupRoute { /// /// {@macro flutter.widgets.RestorationManager} /// -/// ** See code in examples/api/lib/cupertino/route/show_cupertino_modal_popup.0.dart ** -/// {@end-tool} +/// {@example /example/lib/route/show_cupertino_modal_popup.0.dart} +/// +// TODO(framework): End of the @dartpad directive. /// /// See also: /// @@ -1387,7 +1390,9 @@ Widget _buildCupertinoDialogTransitions( /// /// For more information about state restoration, see [RestorationManager]. /// -/// {@tool dartpad} +// 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 /// [CupertinoApp.restorationScopeId] and using [Navigator.restorablePush] to @@ -1395,8 +1400,9 @@ Widget _buildCupertinoDialogTransitions( /// /// {@macro flutter.widgets.RestorationManager} /// -/// ** See code in examples/api/lib/cupertino/route/show_cupertino_dialog.0.dart ** -/// {@end-tool} +/// {@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 7c17da2aac2b..4f08927be983 100644 --- a/packages/cupertino_ui/lib/src/scrollbar.dart +++ b/packages/cupertino_ui/lib/src/scrollbar.dart @@ -43,23 +43,29 @@ const double _kScrollbarCrossAxisMargin = 3.0; /// animate from [thickness] and [radius] to [thicknessWhileDragging] and /// [radiusWhileDragging], respectively. /// -/// {@tool dartpad} +// 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. /// The `thickness` of the scrollbar will animate from 6 pixels to the `thicknessWhileDragging` of 10 /// 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. /// -/// ** See code in examples/api/lib/cupertino/scrollbar/cupertino_scrollbar.0.dart ** -/// {@end-tool} +/// {@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 /// -/// {@tool dartpad} /// 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. /// -/// ** See code in examples/api/lib/cupertino/scrollbar/cupertino_scrollbar.1.dart ** -/// {@end-tool} +/// {@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 38be52d88bcf..7216749f4c6d 100644 --- a/packages/cupertino_ui/lib/src/search_field.dart +++ b/packages/cupertino_ui/lib/src/search_field.dart @@ -38,23 +38,29 @@ 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: /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/search_field/cupertino_search_field.0.dart ** -/// {@end-tool} +/// {@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: /// -/// {@tool dartpad} +// 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]. /// -/// ** See code in examples/api/lib/cupertino/search_field/cupertino_search_field.1.dart ** -/// {@end-tool} +/// {@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 25c3230bae88..d527f930f2b7 100644 --- a/packages/cupertino_ui/lib/src/segmented_control.dart +++ b/packages/cupertino_ui/lib/src/segmented_control.dart @@ -70,7 +70,9 @@ const Duration _kFadeDuration = Duration(milliseconds: 165); /// [disabledChildren]. If the child is not present in the [Set], it is enabled /// by default. /// -/// {@tool dartpad} +// 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. /// /// The callback provided to [onValueChanged] should update the state of @@ -80,8 +82,9 @@ 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. /// -/// ** See code in examples/api/lib/cupertino/segmented_control/cupertino_segmented_control.0.dart ** -/// {@end-tool} +/// {@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 60bb2a6b1844..9f2bedb650d5 100644 --- a/packages/cupertino_ui/lib/src/sheet.dart +++ b/packages/cupertino_ui/lib/src/sheet.dart @@ -158,12 +158,15 @@ 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. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/sheet/cupertino_sheet.1.dart ** -/// {@end-tool} +/// {@example /example/lib/sheet/cupertino_sheet.1.dart} +/// +// TODO(framework): End of the @dartpad directive. /// /// See also: /// @@ -608,25 +611,34 @@ class _StretchDragControllerProvider extends InheritedWidget { /// scrollable area within the sheet, this parameter can be ignored. See below /// for an example. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/sheet/cupertino_sheet.0.dart ** -/// {@end-tool} +/// {@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 /// -/// {@tool dartpad} /// This example shows how to show a Cupertino Sheet with nested navigation manually /// set up in order to enable restorable state. /// -/// ** See code in examples/api/lib/cupertino/sheet/cupertino_sheet.2.dart ** -/// {@end-tool} +/// {@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 /// -/// {@tool dartpad} /// This example shows how to show a Cupertino Sheet with scrollable content. /// -/// ** See code in examples/api/lib/cupertino/sheet/cupertino_sheet.3.dart ** -/// {@end-tool} +/// {@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 @@ -667,11 +679,14 @@ 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. /// - /// {@tool dartpad} + // 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. /// - /// ** See code in examples/api/lib/cupertino/sheet/cupertino_sheet.3.dart ** - /// {@end-tool} + /// {@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 e66129ab2d1e..33047c757022 100644 --- a/packages/cupertino_ui/lib/src/slider.dart +++ b/packages/cupertino_ui/lib/src/slider.dart @@ -52,11 +52,14 @@ 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. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/slider/cupertino_slider.0.dart ** -/// {@end-tool} +/// {@example /example/lib/slider/cupertino_slider.0.dart} +/// +// TODO(framework): End of the @dartpad directive. /// /// See also: /// @@ -137,7 +140,11 @@ class CupertinoSlider extends StatefulWidget { /// The value passed will be the last [value] that the slider had before the /// change began. /// - /// {@tool snippet} + // TODO(framework): Replace the following block with a blue example container + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 + // TODO(framework): Add unit tests to this code snippet. + // https://github.com/flutter/flutter/issues/188530 + /// /// /// ```dart /// CupertinoSlider( @@ -155,7 +162,8 @@ class CupertinoSlider extends StatefulWidget { /// }, /// ) /// ``` - /// {@end-tool} + /// + // TODO(framework): End of the blue example container. /// /// See also: /// @@ -169,7 +177,11 @@ class CupertinoSlider extends StatefulWidget { /// [onChanged] for that), but rather to know when the user has completed /// selecting a new [value] by ending a drag. /// - /// {@tool snippet} + // TODO(framework): Replace the following block with a blue example container + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 + // TODO(framework): Add unit tests to this code snippet. + // https://github.com/flutter/flutter/issues/188530 + /// /// /// ```dart /// CupertinoSlider( @@ -187,7 +199,8 @@ class CupertinoSlider extends StatefulWidget { /// }, /// ) /// ``` - /// {@end-tool} + /// + // TODO(framework): End of the blue example container. /// /// 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 d4be322cafb8..d06ac15a3408 100644 --- a/packages/cupertino_ui/lib/src/sliding_segmented_control.dart +++ b/packages/cupertino_ui/lib/src/sliding_segmented_control.dart @@ -340,15 +340,18 @@ class _SegmentSeparatorState extends State<_SegmentSeparator> /// [thumbColor], [backgroundColor] arguments can be used to override the /// segmented control's colors from its defaults. /// -/// {@tool dartpad} +// 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. /// /// The callback provided to [onValueChanged] should update the state of /// the parent [StatefulWidget] using the [State.setState] method, so that /// the parent gets rebuilt; for example: /// -/// ** See code in examples/api/lib/cupertino/segmented_control/cupertino_sliding_segmented_control.0.dart ** -/// {@end-tool} +/// {@example /example/lib/segmented_control/cupertino_sliding_segmented_control.0.dart} +/// +// TODO(framework): End of the @dartpad directive. /// See also: /// /// * @@ -424,7 +427,11 @@ class CupertinoSlidingSegmentedControl extends StatefulWidget /// the parent [StatefulWidget] using the [State.setState] method, so that /// the parent gets rebuilt; for example: /// - /// {@tool snippet} + // TODO(framework): Replace the following block with a blue example container + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 + // TODO(framework): Add unit tests to this code snippet. + // https://github.com/flutter/flutter/issues/188530 + /// /// /// ```dart /// class SegmentedControlExample extends StatefulWidget { @@ -456,7 +463,8 @@ class CupertinoSlidingSegmentedControl extends StatefulWidget /// } /// } /// ``` - /// {@end-tool} + /// + // TODO(framework): End of the blue example container. final ValueChanged onValueChanged; /// The color used to paint the rounded rect behind the [children] and the separators. @@ -500,13 +508,16 @@ class CupertinoSlidingSegmentedControl extends StatefulWidget /// /// Defaults to false. /// - /// {@tool dartpad} + // 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. /// - /// ** See code in examples/api/lib/cupertino/segmented_control/cupertino_sliding_segmented_control.0.dart ** - /// {@end-tool} + /// {@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 fbf3f0a68c4b..4db1901d3222 100644 --- a/packages/cupertino_ui/lib/src/switch.dart +++ b/packages/cupertino_ui/lib/src/switch.dart @@ -77,14 +77,21 @@ const CupertinoDynamicColor _kOffLabelColor = CupertinoDynamicColor.withBrightne /// callback and rebuild the switch with a new [value] to update the visual /// appearance of the switch. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/switch/cupertino_switch.0.dart ** -/// {@end-tool} +/// {@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 +// TODO(framework): Add unit tests to this code snippet. +// https://github.com/flutter/flutter/issues/188530 /// -/// {@tool snippet} /// /// This sample shows how to use a [CupertinoSwitch] in a [CupertinoListTile]. The /// [MergeSemantics] is used to turn the entire [CupertinoListTile] into a single item @@ -102,7 +109,8 @@ const CupertinoDynamicColor _kOffLabelColor = CupertinoDynamicColor.withBrightne /// ), /// ) /// ``` -/// {@end-tool} +/// +// TODO(framework): End of the blue example container. /// /// See also: /// @@ -297,7 +305,11 @@ class CupertinoSwitch extends StatefulWidget { /// * [WidgetState.focused]. /// * [WidgetState.disabled]. /// - /// {@tool snippet} + // TODO(framework): Replace the following block with a blue example container + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 + // TODO(framework): Add unit tests to this code snippet. + // https://github.com/flutter/flutter/issues/188530 + /// /// This example resolves the [trackOutlineColor] based on the current /// [WidgetState] of the [CupertinoSwitch], providing a different [Color] when it is /// [WidgetState.disabled]. @@ -314,7 +326,8 @@ class CupertinoSwitch extends StatefulWidget { /// }), /// ) /// ``` - /// {@end-tool} + /// + // TODO(framework): End of the blue example container. /// /// The [CupertinoSwitch] track has no outline by default. final WidgetStateProperty? trackOutlineColor; @@ -327,7 +340,11 @@ class CupertinoSwitch extends StatefulWidget { /// * [WidgetState.focused]. /// * [WidgetState.disabled]. /// - /// {@tool snippet} + // TODO(framework): Replace the following block with a blue example container + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 + // TODO(framework): Add unit tests to this code snippet. + // https://github.com/flutter/flutter/issues/188530 + /// /// This example resolves the [trackOutlineWidth] based on the current /// [WidgetState] of the [CupertinoSwitch], providing a different outline width when it is /// [WidgetState.disabled]. @@ -344,7 +361,8 @@ class CupertinoSwitch extends StatefulWidget { /// }), /// ) /// ``` - /// {@end-tool} + /// + // TODO(framework): End of the blue example container. /// /// Since a [CupertinoSwitch] has no track outline by default, this parameter /// is set only if [trackOutlineColor] is provided. @@ -360,7 +378,11 @@ class CupertinoSwitch extends StatefulWidget { /// * [WidgetState.focused]. /// * [WidgetState.disabled]. /// - /// {@tool snippet} + // TODO(framework): Replace the following block with a blue example container + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 + // TODO(framework): Add unit tests to this code snippet. + // https://github.com/flutter/flutter/issues/188530 + /// /// This example resolves the [thumbIcon] based on the current /// [WidgetState] of the [CupertinoSwitch], providing a different [Icon] when it is /// [WidgetState.disabled]. @@ -377,7 +399,8 @@ class CupertinoSwitch extends StatefulWidget { /// }), /// ) /// ``` - /// {@end-tool} + /// + // TODO(framework): End of the blue example container. /// /// If null, then the [CupertinoSwitch] does not have any icons on the thumb. final WidgetStateProperty? thumbIcon; @@ -391,7 +414,11 @@ class CupertinoSwitch extends StatefulWidget { /// * [WidgetState.focused]. /// * [WidgetState.disabled]. /// - /// {@tool snippet} + // TODO(framework): Replace the following block with a blue example container + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 + // TODO(framework): Add unit tests to this code snippet. + // https://github.com/flutter/flutter/issues/188530 + /// /// This example resolves the [mouseCursor] based on the current /// [WidgetState] of the [CupertinoSwitch], providing a different [mouseCursor] when it is /// [WidgetState.disabled]. @@ -408,7 +435,8 @@ class CupertinoSwitch extends StatefulWidget { /// }), /// ) /// ``` - /// {@end-tool} + /// + // TODO(framework): End of the blue example container. /// /// If null, then [MouseCursor.defer] is used when the switch is disabled. /// When the switch is enabled, [SystemMouseCursors.click] is used on Web, and diff --git a/packages/cupertino_ui/lib/src/tab_scaffold.dart b/packages/cupertino_ui/lib/src/tab_scaffold.dart index 51e1d5aca869..55ca8e30cc30 100644 --- a/packages/cupertino_ui/lib/src/tab_scaffold.dart +++ b/packages/cupertino_ui/lib/src/tab_scaffold.dart @@ -22,12 +22,15 @@ import 'theme.dart'; /// [CupertinoTabController] controls, as well as the currently selected tab item of /// its [CupertinoTabBar]. /// -/// {@tool dartpad} +// 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]. /// -/// ** See code in examples/api/lib/cupertino/tab_scaffold/cupertino_tab_controller.0.dart ** -/// {@end-tool} +/// {@example /example/lib/tab_scaffold/cupertino_tab_controller.0.dart} +/// +// TODO(framework): End of the @dartpad directive. /// /// See also: /// @@ -105,11 +108,14 @@ class CupertinoTabController extends ChangeNotifier { /// (via [State.setState], for instance) from its descendant rather than from /// its ancestor. /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/tab_scaffold/cupertino_tab_scaffold.0.dart ** -/// {@end-tool} +/// {@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 8156cea8f1ed..32612565d1f3 100644 --- a/packages/cupertino_ui/lib/src/text_field.dart +++ b/packages/cupertino_ui/lib/src/text_field.dart @@ -147,12 +147,15 @@ class _CupertinoTextFieldSelectionGestureDetectorBuilder /// /// {@macro flutter.widgets.EditableText.onChanged} /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/text_field/cupertino_text_field.0.dart ** -/// {@end-tool} +/// {@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). @@ -834,11 +837,16 @@ class CupertinoTextField extends StatefulWidget { /// /// {@macro flutter.widgets.magnifier.intro} /// - /// {@tool dartpad} + // TODO(framework): Replace the following block with a blue example container + // when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 + // TODO(framework): Add unit tests to this code snippet. + // https://github.com/flutter/flutter/issues/188530 + /// /// This sample demonstrates how to customize the magnifier that this text field uses. /// - /// ** See code in examples/api/lib/widgets/text_magnifier/text_magnifier.0.dart ** - /// {@end-tool} + /// {@example example/lib/magnifier/text_magnifier.0.dart} + /// + // TODO(framework): End of the blue example container. final TextMagnifierConfiguration? magnifierConfiguration; /// {@macro flutter.widgets.EditableText.spellCheckConfiguration} 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 51517091cf40..9de408b852a2 100644 --- a/packages/cupertino_ui/lib/src/text_form_field_row.dart +++ b/packages/cupertino_ui/lib/src/text_form_field_row.dart @@ -48,7 +48,11 @@ import 'text_field.dart'; /// [CupertinoTextField] class and [CupertinoTextField.borderless], /// the constructor. /// -/// {@tool snippet} +// TODO(framework): Replace the following block with a blue example container +// when it's supported. https://github.com/dart-lang/dartdoc/issues/4243 +// TODO(framework): Add unit tests to this code snippet. +// https://github.com/flutter/flutter/issues/188530 +/// /// /// Creates a [CupertinoTextFormFieldRow] with a leading text and validator /// function. @@ -71,14 +75,18 @@ import 'text_field.dart'; /// }, /// ) /// ``` -/// {@end-tool} /// -/// {@tool dartpad} +// 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. /// -/// ** See code in examples/api/lib/cupertino/text_form_field_row/cupertino_text_form_field_row.1.dart ** -/// {@end-tool} +/// {@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].