Skip to content

Commit ea69ee2

Browse files
[material_ui] Document how to programmatically clear DropdownMenu selection
Improve documentation and add an interactive sample demonstrating how to programmatically clear or reset the selection in DropdownMenu using a TextEditingController alongside resetting the state variable. Fixes flutter/flutter#177599
1 parent 93baed9 commit ea69ee2

4 files changed

Lines changed: 210 additions & 3 deletions

File tree

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
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+
// #region body
6+
import 'package:material_ui/material_ui.dart';
7+
8+
/// Flutter code sample for [DropdownMenu] showing how to programmatically
9+
/// clear or reset the selection using a [TextEditingController].
10+
11+
void main() => runApp(const DropdownMenuClearExampleApp());
12+
13+
class DropdownMenuClearExampleApp extends StatelessWidget {
14+
const DropdownMenuClearExampleApp({super.key});
15+
16+
@override
17+
Widget build(BuildContext context) {
18+
return MaterialApp(
19+
home: Scaffold(
20+
appBar: AppBar(title: const Text('Clear DropdownMenu Sample')),
21+
body: const Center(child: DropdownMenuClearExample()),
22+
),
23+
);
24+
}
25+
}
26+
27+
class DropdownMenuClearExample extends StatefulWidget {
28+
const DropdownMenuClearExample({super.key});
29+
30+
@override
31+
State<DropdownMenuClearExample> createState() =>
32+
_DropdownMenuClearExampleState();
33+
}
34+
35+
enum ColorItem {
36+
red('Red'),
37+
green('Green'),
38+
blue('Blue');
39+
40+
const ColorItem(this.label);
41+
final String label;
42+
}
43+
44+
class _DropdownMenuClearExampleState extends State<DropdownMenuClearExample> {
45+
final TextEditingController _controller = TextEditingController();
46+
ColorItem? _selectedColor;
47+
48+
@override
49+
void dispose() {
50+
_controller.dispose();
51+
super.dispose();
52+
}
53+
54+
void _clearSelection() {
55+
setState(() {
56+
_selectedColor = null;
57+
_controller.clear();
58+
});
59+
}
60+
61+
@override
62+
Widget build(BuildContext context) {
63+
return Column(
64+
mainAxisAlignment: MainAxisAlignment.center,
65+
children: <Widget>[
66+
DropdownMenu<ColorItem>(
67+
controller: _controller,
68+
initialSelection: _selectedColor,
69+
label: const Text('Color'),
70+
onSelected: (ColorItem? color) {
71+
setState(() {
72+
_selectedColor = color;
73+
});
74+
},
75+
dropdownMenuEntries: ColorItem.values
76+
.map<DropdownMenuEntry<ColorItem>>((ColorItem color) {
77+
return DropdownMenuEntry<ColorItem>(
78+
value: color,
79+
label: color.label,
80+
);
81+
})
82+
.toList(),
83+
),
84+
const SizedBox(height: 20),
85+
FilledButton(
86+
onPressed: _clearSelection,
87+
child: const Text('Clear selection'),
88+
),
89+
const SizedBox(height: 20),
90+
Text('Selected: ${_selectedColor?.label ?? 'None'}'),
91+
],
92+
);
93+
}
94+
}
95+
// #endregion body
Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
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_test/flutter_test.dart';
6+
import 'package:material_ui/material_ui.dart';
7+
import 'package:material_ui_examples/dropdown_menu/dropdown_menu.3.dart'
8+
as example;
9+
10+
void main() {
11+
testWidgets('Selecting an entry updates the text field and state', (
12+
WidgetTester tester,
13+
) async {
14+
await tester.pumpWidget(const example.DropdownMenuClearExampleApp());
15+
16+
expect(find.text('Selected: None'), findsOneWidget);
17+
expect(find.widgetWithText(TextField, ''), findsOneWidget);
18+
19+
// Open menu and select Green.
20+
await tester.tap(find.byType(DropdownMenu<example.ColorItem>));
21+
await tester.pumpAndSettle();
22+
23+
await tester.tap(find.widgetWithText(MenuItemButton, 'Green').last);
24+
await tester.pumpAndSettle();
25+
26+
expect(find.text('Selected: Green'), findsOneWidget);
27+
expect(find.widgetWithText(TextField, 'Green'), findsOneWidget);
28+
});
29+
30+
testWidgets(
31+
'Pressing clear selection button resets the text field and state',
32+
(WidgetTester tester) async {
33+
await tester.pumpWidget(const example.DropdownMenuClearExampleApp());
34+
35+
// Open menu and select Blue.
36+
await tester.tap(find.byType(DropdownMenu<example.ColorItem>));
37+
await tester.pumpAndSettle();
38+
39+
await tester.tap(find.widgetWithText(MenuItemButton, 'Blue').last);
40+
await tester.pumpAndSettle();
41+
42+
expect(find.text('Selected: Blue'), findsOneWidget);
43+
expect(find.widgetWithText(TextField, 'Blue'), findsOneWidget);
44+
45+
// Tap clear button.
46+
await tester.tap(find.widgetWithText(FilledButton, 'Clear selection'));
47+
await tester.pumpAndSettle();
48+
49+
expect(find.text('Selected: None'), findsOneWidget);
50+
expect(find.widgetWithText(TextField, ''), findsOneWidget);
51+
},
52+
);
53+
}

‎packages/material_ui/lib/src/dropdown_menu.dart‎

Lines changed: 59 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,19 @@ enum DropdownMenuCloseBehavior {
183183
///
184184
/// </callout-box>
185185
///
186+
/// <callout-box>
187+
///
188+
/// This sample demonstrates how to programmatically clear or reset the selection
189+
/// in a [DropdownMenu] using a [TextEditingController].
190+
///
191+
// TODO(framework): Replace the following block with a @dartpad directive
192+
// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123
193+
/// {@macro material_ui.dartpad_guide}
194+
///
195+
/// {@example /example/lib/dropdown_menu/dropdown_menu.3.dart#body}
196+
///
197+
/// </callout-box>
198+
///
186199
/// See also:
187200
///
188201
/// * [MenuAnchor], which is a widget used to mark the "anchor" for a set of submenus.
@@ -448,6 +461,33 @@ class DropdownMenu<T> extends StatefulWidget {
448461
/// Controls the text being edited or selected in the menu.
449462
///
450463
/// If null, this widget will create its own [TextEditingController].
464+
///
465+
/// A [TextEditingController] can be provided to programmatically clear or modify
466+
/// the displayed selection. For example, calling [TextEditingController.clear]
467+
/// clears the text displayed in the dropdown menu.
468+
///
469+
/// When tracking the selected value in a state variable, calling
470+
/// [TextEditingController.clear] alongside updating the state variable to null
471+
/// is required to clear the displayed selection, as updating [initialSelection]
472+
/// does not clear the text field.
473+
///
474+
/// <callout-box>
475+
///
476+
/// This sample demonstrates how to programmatically clear the selection in a
477+
/// [DropdownMenu] using a [TextEditingController].
478+
///
479+
// TODO(framework): Replace the following block with a @dartpad directive
480+
// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123
481+
/// {@macro material_ui.dartpad_guide}
482+
///
483+
/// {@example /example/lib/dropdown_menu/dropdown_menu.3.dart#body}
484+
///
485+
/// </callout-box>
486+
///
487+
/// See also:
488+
///
489+
/// * [initialSelection], which sets the initial selection when the widget is
490+
/// first created.
451491
final TextEditingController? controller;
452492

453493
/// The value used for an initial selection.
@@ -456,13 +496,29 @@ class DropdownMenu<T> extends StatefulWidget {
456496
/// is first created. If the value matches one of the [dropdownMenuEntries],
457497
/// the corresponding label will be displayed in the text field.
458498
///
459-
/// Setting this to null does not clear the text field.
499+
/// Setting this to null does not clear the text field because [initialSelection]
500+
/// only specifies an initial selection and does not act as a reactive, controlled
501+
/// selection property.
460502
///
461-
/// To programmatically clear the text field, use a [TextEditingController]
462-
/// and call [TextEditingController.clear] on it.
503+
/// To programmatically clear or reset the selection, provide a [controller]
504+
/// and call [TextEditingController.clear] on it alongside resetting the state
505+
/// variable to null.
463506
///
464507
/// Defaults to null.
465508
///
509+
/// <callout-box>
510+
///
511+
/// This sample demonstrates how to programmatically clear the selection in a
512+
/// [DropdownMenu] using a [TextEditingController].
513+
///
514+
// TODO(framework): Replace the following block with a @dartpad directive
515+
// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123
516+
/// {@macro material_ui.dartpad_guide}
517+
///
518+
/// {@example /example/lib/dropdown_menu/dropdown_menu.3.dart#body}
519+
///
520+
/// </callout-box>
521+
///
466522
/// See also:
467523
///
468524
/// * [controller], which is required to programmatically clear or modify
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
changelog: |
2+
- Clarifies how to programmatically clear or reset the selection in `DropdownMenu`.
3+
version: patch

0 commit comments

Comments
 (0)