Skip to content

Commit 4d9a598

Browse files
committed
RawAutocomplete: Add controller param for caller-managed options
Fixes flutter#159443. RawAutocomplete.optionsBuilder only receives a TextEditingValue, so it cannot react to changes in external state (e.g. a data source that loads asynchronously after focus). This adds RawAutocompleteController, a ChangeNotifier with an options getter/setter, and a new controller param on RawAutocomplete that is mutually exclusive with optionsBuilder. When a controller is provided, the caller sets controller.options directly and the widget reacts. Internally, the state now uses RawAutocompleteController for both paths: optionsBuilder results flow through an internal controller, while an external controller is used directly. The post-update work (semantics announcements, highlight clamping, selection validity, visibility) is extracted into _handleOptionsChanged, which listens to whichever controller is active.
1 parent b15478e commit 4d9a598

2 files changed

Lines changed: 210 additions & 24 deletions

File tree

‎packages/flutter/lib/src/widgets/autocomplete.dart‎

Lines changed: 116 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -121,19 +121,50 @@ enum OptionsViewOpenDirection {
121121
mostSpace,
122122
}
123123

124+
/// A controller for a [RawAutocomplete] widget
125+
/// that allows the caller to manage the options list directly
126+
/// instead of using a [RawAutocomplete.optionsBuilder] callback.
127+
///
128+
/// This is useful when the options depend on criteria beyond just the
129+
/// [TextEditingValue], which is the only input
130+
/// that [RawAutocomplete.optionsBuilder] receives.
131+
///
132+
/// Provide a [RawAutocompleteController] to [RawAutocomplete.controller] and
133+
/// set [options] to update the displayed options. The widget will react to
134+
/// changes in the controller's options and show/hide the options view
135+
/// accordingly.
136+
///
137+
/// See also:
138+
///
139+
/// * [RawAutocomplete.controller], which accepts this controller.
140+
/// * [RawAutocomplete.optionsBuilder], the callback-based alternative.
141+
class RawAutocompleteController<T extends Object> extends ChangeNotifier {
142+
/// The current list of selectable options.
143+
Iterable<T> get options => _options;
144+
Iterable<T> _options = Iterable<T>.empty();
145+
set options(Iterable<T> value) {
146+
if (value == _options) {
147+
return;
148+
}
149+
_options = value;
150+
notifyListeners();
151+
}
152+
}
153+
124154
// TODO(justinmc): Mention AutocompleteCupertino when it is implemented.
125155
/// {@template flutter.widgets.RawAutocomplete.RawAutocomplete}
126156
/// A widget for helping the user make a selection by entering some text and
127157
/// choosing from among a list of options.
128158
///
129159
/// The user's text input is received in a field built with the
130160
/// [fieldViewBuilder] parameter. The options to be displayed are determined
131-
/// using [optionsBuilder] and rendered with [optionsViewBuilder].
161+
/// using [optionsBuilder] (or, for [RawAutocomplete], a
162+
/// [RawAutocompleteController]) and
163+
/// rendered with [optionsViewBuilder].
132164
///
133-
/// The options view opens when the field gains focus or when the field's text
134-
/// changes, as long as [optionsBuilder] returns at least one option. The options
135-
/// view closes when the user selects an option, when there are no matching
136-
/// options, or when the field loses focus.
165+
/// The options view opens when the field gains focus and there is at least one
166+
/// option available. It closes when the user selects an option, when there are
167+
/// no matching options, or when the field loses focus.
137168
/// {@endtemplate}
138169
///
139170
/// This is a core framework widget with very basic UI.
@@ -171,12 +202,16 @@ enum OptionsViewOpenDirection {
171202
class RawAutocomplete<T extends Object> extends StatefulWidget {
172203
/// Create an instance of RawAutocomplete.
173204
///
174-
/// [displayStringForOption], [optionsBuilder] and [optionsViewBuilder] must
175-
/// not be null.
205+
/// Exactly one of [optionsBuilder] or [controller] must be provided.
206+
/// When [optionsBuilder] is provided, the widget internally calls it when the
207+
/// text field's [TextEditingValue] changes and manages the result.
208+
/// When [controller] is provided, the caller sets
209+
/// [RawAutocompleteController.options] directly and the widget reacts.
176210
const RawAutocomplete({
177211
super.key,
178212
required this.optionsViewBuilder,
179-
required this.optionsBuilder,
213+
this.optionsBuilder,
214+
this.controller,
180215
this.optionsViewOpenDirection = OptionsViewOpenDirection.down,
181216
this.displayStringForOption = defaultStringForOption,
182217
this.fieldViewBuilder,
@@ -193,6 +228,10 @@ class RawAutocomplete<T extends Object> extends StatefulWidget {
193228
assert(
194229
!(textEditingController != null && initialValue != null),
195230
'textEditingController and initialValue cannot be simultaneously defined.',
231+
),
232+
assert(
233+
(optionsBuilder == null) != (controller == null),
234+
'Exactly one of optionsBuilder or controller must be provided.',
196235
);
197236

198237
/// {@template flutter.widgets.RawAutocomplete.fieldViewBuilder}
@@ -277,7 +316,19 @@ class RawAutocomplete<T extends Object> extends StatefulWidget {
277316
/// A function that returns the current selectable options objects given the
278317
/// current TextEditingValue.
279318
/// {@endtemplate}
280-
final AutocompleteOptionsBuilder<T> optionsBuilder;
319+
///
320+
/// Mutually exclusive with [controller]. Exactly one must be provided.
321+
final AutocompleteOptionsBuilder<T>? optionsBuilder;
322+
323+
/// A controller that allows the caller to manage the options list directly.
324+
///
325+
/// When provided, the caller sets [RawAutocompleteController.options]
326+
/// directly and the widget reacts to changes. This is useful when the
327+
/// options depend on criteria beyond just the [TextEditingValue], which is
328+
/// the only input that [optionsBuilder] receives.
329+
///
330+
/// Mutually exclusive with [optionsBuilder]. Exactly one must be provided.
331+
final RawAutocompleteController<T>? controller;
281332

282333
/// The [TextEditingController] that is used for the text field.
283334
///
@@ -383,7 +434,15 @@ class _RawAutocompleteState<T extends Object> extends State<RawAutocomplete<T>>
383434
DismissIntent: CallbackAction<DismissIntent>(onInvoke: _hideOptions),
384435
};
385436

386-
Iterable<T> _options = Iterable<T>.empty();
437+
RawAutocompleteController<T>? _internalController;
438+
RawAutocompleteController<T> get _controller {
439+
return widget.controller ??
440+
(_internalController ??= RawAutocompleteController<T>()
441+
..addListener(_handleOptionsChanged));
442+
}
443+
444+
Iterable<T> get _options => _controller.options;
445+
bool _lastOptionsWereEmpty = true;
387446
T? _selection;
388447
// Set the initial value to null so when this widget gets focused for the first
389448
// time it will try to run the options view builder.
@@ -472,28 +531,44 @@ class _RawAutocompleteState<T extends Object> extends State<RawAutocomplete<T>>
472531
_userHidOptions = false;
473532
}
474533
_lastFieldText = value.text;
475-
_onChangedCallId += 1;
476-
final int callId = _onChangedCallId;
477-
final Iterable<T> options = await widget.optionsBuilder(value);
478534

479-
if (!mounted) {
480-
return;
481-
}
535+
if (widget.optionsBuilder case final optionsBuilder?) {
536+
_onChangedCallId += 1;
537+
final int callId = _onChangedCallId;
538+
final Iterable<T> options = await optionsBuilder(value);
482539

483-
// Makes sure that previous call results do not replace new ones.
484-
if (callId != _onChangedCallId) {
485-
return;
540+
if (!mounted) {
541+
return;
542+
}
543+
544+
// Makes sure that previous call results do not replace new ones.
545+
if (callId != _onChangedCallId) {
546+
return;
547+
}
548+
_controller.options = options; // triggers _handleOptionsChanged via listener
549+
} else {
550+
// External controller: caller manages options separately.
551+
// Still update selection validity and visibility for text changes.
552+
_updateSelectionValidity();
486553
}
487-
if (_options.isEmpty != options.isEmpty) {
488-
_announceSemantics(options.isNotEmpty);
554+
}
555+
556+
void _handleOptionsChanged() {
557+
final bool optionsWereEmpty = _lastOptionsWereEmpty;
558+
_lastOptionsWereEmpty = _options.isEmpty;
559+
if (optionsWereEmpty != _options.isEmpty) {
560+
_announceSemantics(_options.isNotEmpty);
489561
}
490-
_options = options;
491562
_updateHighlight(_highlightedOptionIndex.value);
563+
_updateSelectionValidity();
564+
}
565+
566+
void _updateSelectionValidity() {
492567
final T? selection = _selection;
493-
if (selection != null && value.text != widget.displayStringForOption(selection)) {
568+
if (selection != null &&
569+
_textEditingController.text != widget.displayStringForOption(selection)) {
494570
_selection = null;
495571
}
496-
497572
_updateOptionsViewVisibility();
498573
}
499574

@@ -648,6 +723,10 @@ class _RawAutocompleteState<T extends Object> extends State<RawAutocomplete<T>>
648723
@override
649724
void initState() {
650725
super.initState();
726+
if (widget.controller != null) {
727+
widget.controller!.addListener(_handleOptionsChanged);
728+
_lastOptionsWereEmpty = widget.controller!.options.isEmpty;
729+
}
651730
final TextEditingController initialController =
652731
widget.textEditingController ??
653732
(_internalTextEditingController = TextEditingController.fromValue(widget.initialValue));
@@ -659,6 +738,17 @@ class _RawAutocompleteState<T extends Object> extends State<RawAutocomplete<T>>
659738
@override
660739
void didUpdateWidget(RawAutocomplete<T> oldWidget) {
661740
super.didUpdateWidget(oldWidget);
741+
if (!identical(oldWidget.controller, widget.controller)) {
742+
oldWidget.controller?.removeListener(_handleOptionsChanged);
743+
if (oldWidget.controller == null) {
744+
_internalController?.dispose();
745+
_internalController = null;
746+
}
747+
if (widget.controller != null) {
748+
widget.controller!.addListener(_handleOptionsChanged);
749+
_lastOptionsWereEmpty = widget.controller!.options.isEmpty;
750+
}
751+
}
662752
if (!identical(oldWidget.textEditingController, widget.textEditingController)) {
663753
oldWidget.textEditingController?.removeListener(_onChangedField);
664754
if (oldWidget.textEditingController == null) {
@@ -679,6 +769,8 @@ class _RawAutocompleteState<T extends Object> extends State<RawAutocomplete<T>>
679769

680770
@override
681771
void dispose() {
772+
widget.controller?.removeListener(_handleOptionsChanged);
773+
_internalController?.dispose();
682774
widget.textEditingController?.removeListener(_onChangedField);
683775
_internalTextEditingController?.dispose();
684776
widget.focusNode?.removeListener(_onFocusChange);

‎packages/flutter/test/widgets/autocomplete_test.dart‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3980,4 +3980,98 @@ void main() {
39803980
// Now text up to cursor is "go", which matches more options.
39813981
expect(lastOptions, <String>['dingo', 'flamingo', 'goose']);
39823982
});
3983+
3984+
group('RawAutocompleteController', () {
3985+
testWidgets('shows, updates, and hides options view', (WidgetTester tester) async {
3986+
final GlobalKey fieldKey = GlobalKey();
3987+
final GlobalKey optionsKey = GlobalKey();
3988+
final controller = RawAutocompleteController<String>();
3989+
addTearDown(controller.dispose);
3990+
late FocusNode focusNode;
3991+
late Iterable<String> lastOptions;
3992+
3993+
await tester.pumpWidget(
3994+
MaterialApp(
3995+
home: Scaffold(
3996+
body: RawAutocomplete<String>(
3997+
controller: controller,
3998+
fieldViewBuilder:
3999+
(
4000+
BuildContext context,
4001+
TextEditingController fieldTextEditingController,
4002+
FocusNode fieldFocusNode,
4003+
VoidCallback onFieldSubmitted,
4004+
) {
4005+
focusNode = fieldFocusNode;
4006+
return TestTextField(
4007+
key: fieldKey,
4008+
focusNode: focusNode,
4009+
controller: fieldTextEditingController,
4010+
);
4011+
},
4012+
optionsViewBuilder:
4013+
(
4014+
BuildContext context,
4015+
AutocompleteOnSelected<String> onSelected,
4016+
Iterable<String> options,
4017+
) {
4018+
lastOptions = options;
4019+
return Container(key: optionsKey);
4020+
},
4021+
),
4022+
),
4023+
),
4024+
);
4025+
4026+
// Set options and focus — options view shows.
4027+
controller.options = kOptions;
4028+
focusNode.requestFocus();
4029+
await tester.pump();
4030+
expect(find.byKey(optionsKey), findsOneWidget);
4031+
expect(lastOptions.length, kOptions.length);
4032+
4033+
// Update to a subset.
4034+
controller.options = <String>['aardvark', 'bobcat'];
4035+
await tester.pump();
4036+
expect(lastOptions.length, 2);
4037+
expect(lastOptions.elementAt(0), 'aardvark');
4038+
expect(lastOptions.elementAt(1), 'bobcat');
4039+
4040+
// Set to empty — options view hides.
4041+
controller.options = <String>[];
4042+
await tester.pump();
4043+
expect(find.byKey(optionsKey), findsNothing);
4044+
});
4045+
4046+
testWidgets('assertion: exactly one of optionsBuilder or controller', (
4047+
WidgetTester tester,
4048+
) async {
4049+
final controller = RawAutocompleteController<String>();
4050+
addTearDown(controller.dispose);
4051+
4052+
Widget optionsViewBuilder(
4053+
BuildContext context,
4054+
AutocompleteOnSelected<String> onSelected,
4055+
Iterable<String> options,
4056+
) {
4057+
return Container();
4058+
}
4059+
4060+
// Both provided.
4061+
expect(
4062+
() => RawAutocomplete<String>(
4063+
optionsBuilder: (TextEditingValue value) => <String>[],
4064+
controller: controller,
4065+
optionsViewBuilder: optionsViewBuilder,
4066+
),
4067+
throwsAssertionError,
4068+
);
4069+
4070+
// Neither provided.
4071+
expect(
4072+
() => RawAutocomplete<String>(optionsViewBuilder: optionsViewBuilder),
4073+
throwsAssertionError,
4074+
);
4075+
});
4076+
});
39834077
}

0 commit comments

Comments
 (0)