Cleanup PageTransitionsTheme documentation and add one example (#121701)

Cleanup PageTransitionsTheme documentation and add one example

examples/api/lib/material/page_transitions_theme/page_transitions_theme.0.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// Flutter code sample for [PageTransitionsTheme].
+
+import 'package:flutter/material.dart';
+
+void main() => runApp(const PageTransitionsThemeApp());
+
+class PageTransitionsThemeApp extends StatelessWidget {
+  const PageTransitionsThemeApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      theme: ThemeData(
+        useMaterial3: true,
+        // Defines the page transition animations used by MaterialPageRoute
+        // for different target platforms.
+        // Non-specified target platforms will default to
+        // ZoomPageTransitionsBuilder().
+        pageTransitionsTheme: const PageTransitionsTheme(
+          builders: <TargetPlatform, PageTransitionsBuilder>{
+            TargetPlatform.iOS: CupertinoPageTransitionsBuilder(),
+            TargetPlatform.linux: OpenUpwardsPageTransitionsBuilder(),
+            TargetPlatform.macOS: FadeUpwardsPageTransitionsBuilder(),
+          },
+        ),
+      ),
+      home: const HomePage(),
+    );
+  }
+}
+
+class HomePage extends StatelessWidget {
+  const HomePage({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      backgroundColor: Colors.blueGrey,
+      body: Center(
+        child: ElevatedButton(
+          onPressed: () {
+            Navigator.of(context).push(
+              MaterialPageRoute<SecondPage>(
+                builder: (BuildContext context) => const SecondPage(),
+              ),
+            );
+          },
+          child: const Text('To SecondPage'),
+        ),
+      ),
+    );
+  }
+}
+
+class SecondPage extends StatelessWidget {
+  const SecondPage({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      backgroundColor: Colors.purple[200],
+      body: Center(
+        child: ElevatedButton(
+          onPressed: () {
+            Navigator.of(context).pop();
+          },
+          child: const Text('Back to HomePage'),
+        ),
+      ),
+    );
+  }
+}

examples/api/test/material/page_transitions_theme/page_transitions_theme.0_test.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/material.dart';
+import 'package:flutter_api_samples/material/page_transitions_theme/page_transitions_theme.0.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets('MaterialApp defines a custom PageTransitionsTheme', (WidgetTester tester) async {
+    await tester.pumpWidget(
+      const example.PageTransitionsThemeApp(),
+    );
+
+    final Finder homePage = find.byType(example.HomePage);
+    expect(homePage, findsOneWidget);
+
+    final PageTransitionsTheme theme = Theme.of(tester.element(homePage)).pageTransitionsTheme;
+    expect(theme.builders, isNotNull);
+
+    // Check defined page transitions builder for each platform.
+    for (final TargetPlatform platform in TargetPlatform.values) {
+      switch (platform) {
+        case TargetPlatform.iOS:
+          expect(theme.builders[platform], isA<CupertinoPageTransitionsBuilder>());
+          break;
+        case TargetPlatform.linux:
+          expect(theme.builders[platform], isA<OpenUpwardsPageTransitionsBuilder>());
+          break;
+        case TargetPlatform.macOS:
+          expect(theme.builders[platform], isA<FadeUpwardsPageTransitionsBuilder>());
+          break;
+        case TargetPlatform.android:
+        case TargetPlatform.fuchsia:
+        case TargetPlatform.windows:
+          expect(theme.builders[platform], isNull);
+          break;
+      }
+    }
+
+    // Can navigate to the second page.
+    expect(find.text('To SecondPage'), findsOneWidget);
+    await tester.tap(find.text('To SecondPage'));
+    await tester.pumpAndSettle();
+
+    // Can navigate back to the home page.
+    expect(find.text('Back to HomePage'), findsOneWidget);
+    await tester.tap(find.text('Back to HomePage'));
+    await tester.pumpAndSettle();
+    expect(find.text('To SecondPage'), findsOneWidget);
+  });
+}

packages/flutter/lib/src/material/page_transitions_theme.dart

@@ -151,7 +151,7 @@ class _OpenUpwardsPageTransition extends StatelessWidget {
 class _ZoomPageTransition extends StatelessWidget {
   /// Creates a [_ZoomPageTransition].
   ///
-  /// The [animation] and [secondaryAnimation] argument are required and must
+  /// The [animation] and [secondaryAnimation] arguments are required and must
   /// not be null.
   const _ZoomPageTransition({
     required this.animation,
@@ -196,9 +196,15 @@ class _ZoomPageTransition extends StatelessWidget {
 
   /// Whether the [SnapshotWidget] will be used.
   ///
-  /// Notably, this improves performance by disabling animations on both the outgoing and
-  /// incoming route. This also implies that ink-splashes or similar animations will
-  /// not animate during the transition.
+  /// When this value is true, performance is improved by disabling animations
+  /// on both the outgoing and incoming route. This also implies that ink-splashes
+  /// or similar animations will not animate during the transition.
+  ///
+  /// See also:
+  ///
+  ///  * [TransitionRoute.allowSnapshotting], which defines wether the route
+  ///    transition will prefer to animate a snapshot of the entering and exiting
+  ///    routes.
   final bool allowSnapshotting;
 
   /// The widget below this widget in the tree.
@@ -669,7 +675,13 @@ class CupertinoPageTransitionsBuilder extends PageTransitionsBuilder {
 /// and delegates to [buildTransitions].
 ///
 /// If a builder with a matching platform is not found, then the
-/// [FadeUpwardsPageTransitionsBuilder] is used.
+/// [ZoomPageTransitionsBuilder] is used.
+///
+/// {@tool dartpad}
+/// This example shows a [MaterialApp] that defines a custom [PageTransitionsTheme].
+///
+/// ** See code in examples/api/lib/material/page_transitions_theme/page_transitions_theme.0.dart **
+/// {@end-tool}
 ///
 /// See also:
 ///
@@ -702,8 +714,9 @@ class PageTransitionsTheme with Diagnosticable {
   Map<TargetPlatform, PageTransitionsBuilder> get builders => _builders;
   final Map<TargetPlatform, PageTransitionsBuilder> _builders;
 
-  /// Delegates to the builder for the current [ThemeData.platform]
-  /// or [ZoomPageTransitionsBuilder].
+  /// Delegates to the builder for the current [ThemeData.platform].
+  /// If a builder for the current platform is not found, then the
+  /// [ZoomPageTransitionsBuilder] is used.
   ///
   /// [MaterialPageRoute.buildTransitions] delegates to this method.
   Widget buildTransitions<T>(
@@ -724,8 +737,8 @@ class PageTransitionsTheme with Diagnosticable {
     return matchingBuilder.buildTransitions<T>(route, context, animation, secondaryAnimation, child);
   }
 
-  // Just used to the builders Map to a list with one PageTransitionsBuilder per platform
-  // for the operator == overload.
+  // Map the builders to a list with one PageTransitionsBuilder per platform for
+  // the operator == overload.
   List<PageTransitionsBuilder?> _all(Map<TargetPlatform, PageTransitionsBuilder> builders) {
     return TargetPlatform.values.map((TargetPlatform platform) => builders[platform]).toList();
   }
@@ -968,7 +981,9 @@ class _ZoomExitTransitionPainter extends SnapshotPainter {
 
   @override
   bool shouldRepaint(covariant _ZoomExitTransitionPainter oldDelegate) {
-    return oldDelegate.reverse != reverse || oldDelegate.fade.value != fade.value || oldDelegate.scale.value != scale.value;
+    return oldDelegate.reverse != reverse
+      || oldDelegate.fade.value != fade.value
+      || oldDelegate.scale.value != scale.value;
   }
 
   @override