Add an example for `AppBar.notificationPredicate` (#106018)

examples/api/lib/material/app_bar/app_bar.3.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 AppBar
+
+import 'package:flutter/material.dart';
+
+List<String> titles = <String>[
+  'Cloud',
+  'Beach',
+  'Sunny',
+];
+
+void main() => runApp(const AppBarApp());
+
+class AppBarApp extends StatelessWidget {
+  const AppBarApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      theme: ThemeData(colorSchemeSeed: const Color(0xff6750a4), useMaterial3: true),
+      home: const AppBarExample(),
+    );
+  }
+}
+
+class AppBarExample extends StatelessWidget {
+  const AppBarExample({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    final ColorScheme colorScheme = Theme.of(context).colorScheme;
+    final Color oddItemColor = colorScheme.primary.withOpacity(0.05);
+    final Color evenItemColor = colorScheme.primary.withOpacity(0.15);
+    const int tabsCount = 3;
+
+    return DefaultTabController(
+      initialIndex: 1,
+      length: tabsCount,
+      child: Scaffold(
+        appBar: AppBar(
+          title: const Text('AppBar Sample'),
+          // This check specifies which nested Scrollable's scroll notification
+          // should be listened to.
+          //
+          // When `ThemeData.useMaterial3` is true and scroll view has
+          // scrolled underneath the app bar, this updates the app bar
+          // background color and elevation.
+          //
+          // This sets `notification.depth == 1` to listen to the scroll
+          // notification from the nested `ListView.builder`.
+          notificationPredicate: (ScrollNotification notification) {
+            return notification.depth == 1;
+          },
+          // The elevation value of the app bar when scroll view has
+          // scrolled underneath the app bar.
+          scrolledUnderElevation: 4.0,
+          shadowColor: Theme.of(context).shadowColor,
+          bottom: TabBar(
+            tabs: <Widget>[
+              Tab(
+                icon: const Icon(Icons.cloud_outlined),
+                text: titles[0],
+              ),
+              Tab(
+                icon: const Icon(Icons.beach_access_sharp),
+                text: titles[1],
+              ),
+              Tab(
+                icon: const Icon(Icons.brightness_5_sharp),
+                text: titles[2],
+              ),
+            ],
+          ),
+        ),
+        body: TabBarView(
+          children: <Widget>[
+            ListView.builder(
+              itemCount: 25,
+              itemBuilder: (BuildContext context, int index) {
+                return  ListTile(
+                  tileColor: index.isOdd ? oddItemColor : evenItemColor,
+                  title: Text('${titles[0]} $index'),
+                );
+              },
+            ),
+            ListView.builder(
+              itemCount: 25,
+              itemBuilder: (BuildContext context, int index) {
+                return  ListTile(
+                  tileColor: index.isOdd ? oddItemColor : evenItemColor,
+                  title: Text('${titles[1]} $index'),
+                );
+              },
+            ),
+            ListView.builder(
+              itemCount: 25,
+              itemBuilder: (BuildContext context, int index) {
+                return  ListTile(
+                  tileColor: index.isOdd ? oddItemColor : evenItemColor,
+                  title: Text('${titles[2]} $index'),
+                );
+              },
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}

examples/api/test/material/appbar/app_bar.3_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/app_bar/app_bar.3.dart' as example;
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  testWidgets(
+    'AppBar elevates when nested scroll view is scrolled underneath the AppBar',
+    (WidgetTester tester) async {
+      Material getMaterial() => tester.widget<Material>(find.descendant(
+        of: find.byType(AppBar),
+        matching: find.byType(Material),
+      ));
+
+      await tester.pumpWidget(
+        const example.AppBarApp(),
+      );
+
+      // Starts with the base elevation.
+      expect(getMaterial().elevation, 0.0);
+
+      await tester.fling(find.text('Beach 3'), const Offset(0.0, -600.0), 2000.0);
+      await tester.pumpAndSettle();
+
+      // After scrolling it should be the scrolledUnderElevation.
+      expect(getMaterial().elevation, 4.0);
+  });
+}

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

@@ -140,6 +140,14 @@ class _PreferredAppBarSize extends Size {
 /// ** See code in examples/api/lib/material/app_bar/app_bar.2.dart **
 /// {@end-tool}
 ///
+/// {@tool dartpad}
+/// 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.
+///
+/// ** See code in examples/api/lib/material/app_bar/app_bar.3.dart **
+/// {@end-tool}
+///
 /// See also:
 ///
 ///  * [Scaffold], which displays the [AppBar] in its [Scaffold.appBar] slot.