Skip to content

Commit e3202be

Browse files
[pointer_interceptor] Adopt code-excerpts for README (flutter#12641)
Replaces the hand-written Dart snippets in `pointer_interceptor`'s README with `<?code-excerpt?>` pragmas backed by a new `example/lib/readme_excerpts.dart`, so the README's examples are validated against compilable, analyzed source (`update-excerpts --fail-on-change`) instead of free-hand text. One of the previous snippets was actually invalid Dart (a stray trailing comma), which this now catches. Also removes the package's `ci_config.yaml`, whose only content was `exempt_from_excerpts: true`, now that the excerpt validation actually runs and passes. Part of flutter#102679. ## Pre-Review Checklist ## Test plan [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling. **Note**: The Flutter team is currently trialing [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from `gemini-code-assist[bot]` aren't authoritative Flutter-team feedback; I'll wait for a human reviewer's guidance on which automated comments (if any) should be addressed.
1 parent b1c05d9 commit e3202be

6 files changed

Lines changed: 186 additions & 35 deletions

File tree

‎packages/pointer_interceptor/pointer_interceptor/CHANGELOG.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
1-
## NEXT
1+
## 0.10.1+3
22

3+
* Adopts `code-excerpt` for the README's Dart snippets so they are validated
4+
against compilable, analyzed source.
35
* Updates minimum supported SDK version to Flutter 3.38/Dart 3.10.
46
* Updates README to reflect currently supported OS versions for the latest
57
versions of the endorsed platform implementations.

‎packages/pointer_interceptor/pointer_interceptor/README.md‎

Lines changed: 42 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# pointer_interceptor
2+
<?code-excerpt path-base="example/lib"?>
23

34
| | iOS | Web |
45
|-------------|---------|-----|
@@ -47,25 +48,27 @@ There's two ways that the `PointerInterceptor` widget can be used to solve the p
4748

4849
1. Wrapping your button element directly (FAB, Custom Play/Pause button...):
4950

50-
```dart
51-
PointerInterceptor(
52-
child: ElevatedButton(...),
53-
)
54-
```
51+
<?code-excerpt "readme_excerpts.dart (WrapButton)"?>
52+
```dart
53+
PointerInterceptor(
54+
child: ElevatedButton(
55+
// ···
56+
),
57+
)
58+
```
5559

5660
2. As a root container for a "layout" element, wrapping a bunch of other elements (like a Drawer):
5761

58-
```dart
59-
Scaffold(
60-
...
61-
drawer: PointerInterceptor(
62-
child: Drawer(
63-
child: ...
64-
),
65-
),
66-
...
67-
)
68-
```
62+
<?code-excerpt "readme_excerpts.dart (WrapSubtree)"?>
63+
```dart
64+
Scaffold(
65+
drawer: PointerInterceptor(
66+
child: Drawer(
67+
// ···
68+
),
69+
),
70+
)
71+
```
6972

7073
### `intercepting`
7174

@@ -76,24 +79,32 @@ The `intercepting` property allows the `PointerInterceptor` widget to render
7679
itself (or not) depending on a boolean value, instead of having to manually
7780
write an `if/else` on the Flutter App widget tree, so code like this:
7881

79-
```dart
80-
if (someCondition) {
81-
return PointerInterceptor(
82-
child: ElevatedButton(...),
83-
)
84-
} else {
85-
return ElevatedButton(...),
86-
}
87-
```
82+
<?code-excerpt "readme_excerpts.dart (InterceptingBefore)"?>
83+
```dart
84+
if (someCondition) {
85+
return PointerInterceptor(
86+
child: ElevatedButton(
87+
// ···
88+
),
89+
);
90+
} else {
91+
return ElevatedButton(
92+
// ···
93+
);
94+
}
95+
```
8896

8997
can be rewritten as:
9098

91-
```dart
92-
return PointerInterceptor(
93-
intercepting: someCondition,
94-
child: ElevatedButton(...),
95-
)
96-
```
99+
<?code-excerpt "readme_excerpts.dart (InterceptingAfter)"?>
100+
```dart
101+
PointerInterceptor(
102+
intercepting: someCondition,
103+
child: ElevatedButton(
104+
// ···
105+
),
106+
)
107+
```
97108

98109
Note: when `intercepting` is false, the `PointerInterceptor` will not render
99110
_anything_ in flutter, and just return its `child`. The code is exactly

‎packages/pointer_interceptor/pointer_interceptor/ci_config.yaml‎

Lines changed: 0 additions & 2 deletions
This file was deleted.
Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
// Copyright 2013 The Flutter Authors
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'package:flutter/material.dart';
6+
import 'package:pointer_interceptor/pointer_interceptor.dart';
7+
8+
/// Wraps a single button so that it can be clicked, even when it's on top of
9+
/// a platform view.
10+
Widget wrapButtonSnippet() {
11+
return
12+
// #docregion WrapButton
13+
PointerInterceptor(
14+
child: ElevatedButton(
15+
// #enddocregion WrapButton
16+
onPressed: () {},
17+
child: const Text('Button'),
18+
// #docregion WrapButton
19+
),
20+
)
21+
// #enddocregion WrapButton
22+
;
23+
}
24+
25+
/// Wraps a whole subtree (a [Drawer], in this case) so that it can be
26+
/// clicked, even when it's on top of a platform view.
27+
Widget wrapSubtreeSnippet() {
28+
return
29+
// #docregion WrapSubtree
30+
Scaffold(
31+
drawer: PointerInterceptor(
32+
child: Drawer(
33+
// #enddocregion WrapSubtree
34+
child: ListView(children: const <Widget>[Text('Drawer contents')]),
35+
// #docregion WrapSubtree
36+
),
37+
),
38+
)
39+
// #enddocregion WrapSubtree
40+
;
41+
}
42+
43+
/// The naive way of conditionally intercepting pointer events, which
44+
/// `intercepting` is meant to replace.
45+
Widget interceptingBeforeSnippet(bool someCondition) {
46+
// #docregion InterceptingBefore
47+
if (someCondition) {
48+
return PointerInterceptor(
49+
child: ElevatedButton(
50+
// #enddocregion InterceptingBefore
51+
onPressed: () {},
52+
child: const Text('Button'),
53+
// #docregion InterceptingBefore
54+
),
55+
);
56+
} else {
57+
return ElevatedButton(
58+
// #enddocregion InterceptingBefore
59+
onPressed: () {},
60+
child: const Text('Button'),
61+
// #docregion InterceptingBefore
62+
);
63+
}
64+
// #enddocregion InterceptingBefore
65+
}
66+
67+
/// The equivalent of [interceptingBeforeSnippet], using `intercepting`.
68+
Widget interceptingAfterSnippet(bool someCondition) {
69+
return
70+
// #docregion InterceptingAfter
71+
PointerInterceptor(
72+
intercepting: someCondition,
73+
child: ElevatedButton(
74+
// #enddocregion InterceptingAfter
75+
onPressed: () {},
76+
child: const Text('Button'),
77+
// #docregion InterceptingAfter
78+
),
79+
)
80+
// #enddocregion InterceptingAfter
81+
;
82+
}
Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
// Copyright 2013 The Flutter Authors
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'package:flutter/material.dart';
6+
import 'package:flutter_test/flutter_test.dart';
7+
import 'package:pointer_interceptor/pointer_interceptor.dart';
8+
import 'package:pointer_interceptor_example/readme_excerpts.dart';
9+
10+
void main() {
11+
testWidgets('wrapButtonSnippet wraps a button in a PointerInterceptor', (
12+
WidgetTester tester,
13+
) async {
14+
await tester.pumpWidget(MaterialApp(home: wrapButtonSnippet()));
15+
16+
expect(find.byType(PointerInterceptor), findsOneWidget);
17+
expect(find.widgetWithText(ElevatedButton, 'Button'), findsOneWidget);
18+
});
19+
20+
testWidgets('wrapSubtreeSnippet wraps a Drawer in a PointerInterceptor', (
21+
WidgetTester tester,
22+
) async {
23+
await tester.pumpWidget(MaterialApp(home: wrapSubtreeSnippet()));
24+
tester.state<ScaffoldState>(find.byType(Scaffold)).openDrawer();
25+
await tester.pumpAndSettle();
26+
27+
expect(find.byType(PointerInterceptor), findsOneWidget);
28+
expect(find.widgetWithText(Drawer, 'Drawer contents'), findsOneWidget);
29+
});
30+
31+
testWidgets('interceptingBeforeSnippet returns a PointerInterceptor when true', (
32+
WidgetTester tester,
33+
) async {
34+
await tester.pumpWidget(MaterialApp(home: interceptingBeforeSnippet(true)));
35+
36+
expect(find.byType(PointerInterceptor), findsOneWidget);
37+
expect(find.widgetWithText(ElevatedButton, 'Button'), findsOneWidget);
38+
});
39+
40+
testWidgets('interceptingBeforeSnippet returns a plain button when false', (
41+
WidgetTester tester,
42+
) async {
43+
await tester.pumpWidget(MaterialApp(home: interceptingBeforeSnippet(false)));
44+
45+
expect(find.byType(PointerInterceptor), findsNothing);
46+
expect(find.widgetWithText(ElevatedButton, 'Button'), findsOneWidget);
47+
});
48+
49+
testWidgets('interceptingAfterSnippet sets intercepting from its argument', (
50+
WidgetTester tester,
51+
) async {
52+
await tester.pumpWidget(MaterialApp(home: interceptingAfterSnippet(true)));
53+
54+
final PointerInterceptor interceptor = tester.widget(find.byType(PointerInterceptor));
55+
expect(interceptor.intercepting, isTrue);
56+
expect(find.widgetWithText(ElevatedButton, 'Button'), findsOneWidget);
57+
});
58+
}

‎packages/pointer_interceptor/pointer_interceptor/pubspec.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ name: pointer_interceptor
22
description: A widget to prevent clicks from being swallowed by underlying HtmlElementViews on the web.
33
repository: https://github.com/flutter/packages/tree/main/packages/pointer_interceptor/pointer_interceptor
44
issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+pointer_interceptor%22
5-
version: 0.10.1+2
5+
version: 0.10.1+3
66

77
environment:
88
sdk: ^3.10.0

0 commit comments

Comments
 (0)