@@ -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 {
171202class 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 (_updateOptionsViewVisibility);
0 commit comments