@@ -121,19 +121,49 @@ enum OptionsViewOpenDirection {
121121 mostSpace,
122122}
123123
124+ /// A controller for a [RawAutocomplete] widget that allows the caller to
125+ /// manage the options list directly instead of using an [optionsBuilder]
126+ /// callback.
127+ ///
128+ /// This is useful when the options depend on criteria beyond just the
129+ /// [TextEditingValue] , which is the only input that [optionsBuilder] receives.
130+ ///
131+ /// Provide a [RawAutocompleteController] to [RawAutocomplete.controller] and
132+ /// set [options] to update the displayed options. The widget will react to
133+ /// changes in the controller's options and show/hide the options view
134+ /// accordingly.
135+ ///
136+ /// See also:
137+ ///
138+ /// * [RawAutocomplete.controller] , which accepts this controller.
139+ /// * [RawAutocomplete.optionsBuilder] , the callback-based alternative.
140+ class RawAutocompleteController <T extends Object > extends ChangeNotifier {
141+ /// The current list of selectable options.
142+ Iterable <T > get options => _options;
143+ Iterable <T > _options = Iterable <T >.empty ();
144+ set options (Iterable <T > value) {
145+ if (value == _options) {
146+ return ;
147+ }
148+ _options = value;
149+ notifyListeners ();
150+ }
151+ }
152+
124153// TODO(justinmc): Mention AutocompleteCupertino when it is implemented.
125154/// {@template flutter.widgets.RawAutocomplete.RawAutocomplete}
126155/// A widget for helping the user make a selection by entering some text and
127156/// choosing from among a list of options.
128157///
129158/// The user's text input is received in a field built with the
130159/// [fieldViewBuilder] parameter. The options to be displayed are determined
131- /// using [optionsBuilder] and rendered with [optionsViewBuilder] .
160+ /// using [optionsBuilder] (or, for [RawAutocomplete] , a
161+ /// [RawAutocompleteController] ) and
162+ /// rendered with [optionsViewBuilder] .
132163///
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.
164+ /// The options view opens when the field gains focus and there is at least one
165+ /// option available. It closes when the user selects an option, when there are
166+ /// no matching options, or when the field loses focus.
137167/// {@endtemplate}
138168///
139169/// This is a core framework widget with very basic UI.
@@ -171,12 +201,16 @@ enum OptionsViewOpenDirection {
171201class RawAutocomplete <T extends Object > extends StatefulWidget {
172202 /// Create an instance of RawAutocomplete.
173203 ///
174- /// [displayStringForOption] , [optionsBuilder] and [optionsViewBuilder] must
175- /// not be null.
204+ /// Exactly one of [optionsBuilder] or [controller] must be provided.
205+ /// When [optionsBuilder] is provided, the widget internally calls it when the
206+ /// text field's [TextEditingValue] changes and manages the result.
207+ /// When [controller] is provided, the caller sets
208+ /// [RawAutocompleteController.options] directly and the widget reacts.
176209 const RawAutocomplete ({
177210 super .key,
178211 required this .optionsViewBuilder,
179- required this .optionsBuilder,
212+ this .optionsBuilder,
213+ this .controller,
180214 this .optionsViewOpenDirection = OptionsViewOpenDirection .down,
181215 this .displayStringForOption = defaultStringForOption,
182216 this .fieldViewBuilder,
@@ -193,6 +227,10 @@ class RawAutocomplete<T extends Object> extends StatefulWidget {
193227 assert (
194228 ! (textEditingController != null && initialValue != null ),
195229 'textEditingController and initialValue cannot be simultaneously defined.' ,
230+ ),
231+ assert (
232+ (optionsBuilder == null ) != (controller == null ),
233+ 'Exactly one of optionsBuilder or controller must be provided.' ,
196234 );
197235
198236 /// {@template flutter.widgets.RawAutocomplete.fieldViewBuilder}
@@ -277,7 +315,19 @@ class RawAutocomplete<T extends Object> extends StatefulWidget {
277315 /// A function that returns the current selectable options objects given the
278316 /// current TextEditingValue.
279317 /// {@endtemplate}
280- final AutocompleteOptionsBuilder <T > optionsBuilder;
318+ ///
319+ /// Mutually exclusive with [controller] . Exactly one must be provided.
320+ final AutocompleteOptionsBuilder <T >? optionsBuilder;
321+
322+ /// A controller that allows the caller to manage the options list directly.
323+ ///
324+ /// When provided, the caller sets [RawAutocompleteController.options]
325+ /// directly and the widget reacts to changes. This is useful when the
326+ /// options depend on criteria beyond just the [TextEditingValue] , which is
327+ /// the only input that [optionsBuilder] receives.
328+ ///
329+ /// Mutually exclusive with [optionsBuilder] . Exactly one must be provided.
330+ final RawAutocompleteController <T >? controller;
281331
282332 /// The [TextEditingController] that is used for the text field.
283333 ///
@@ -383,7 +433,15 @@ class _RawAutocompleteState<T extends Object> extends State<RawAutocomplete<T>>
383433 DismissIntent : CallbackAction <DismissIntent >(onInvoke: _hideOptions),
384434 };
385435
386- Iterable <T > _options = Iterable <T >.empty ();
436+ RawAutocompleteController <T >? _internalController;
437+ RawAutocompleteController <T > get _controller {
438+ return widget.controller ??
439+ (_internalController ?? = RawAutocompleteController <T >()
440+ ..addListener (_handleOptionsChanged));
441+ }
442+
443+ Iterable <T > get _options => _controller.options;
444+ bool _lastOptionsWereEmpty = true ;
387445 T ? _selection;
388446 // Set the initial value to null so when this widget gets focused for the first
389447 // time it will try to run the options view builder.
@@ -472,28 +530,44 @@ class _RawAutocompleteState<T extends Object> extends State<RawAutocomplete<T>>
472530 _userHidOptions = false ;
473531 }
474532 _lastFieldText = value.text;
475- _onChangedCallId += 1 ;
476- final int callId = _onChangedCallId;
477- final Iterable <T > options = await widget.optionsBuilder (value);
478533
479- if (! mounted) {
480- return ;
481- }
534+ if (widget.optionsBuilder case final optionsBuilder? ) {
535+ _onChangedCallId += 1 ;
536+ final int callId = _onChangedCallId;
537+ final Iterable <T > options = await optionsBuilder (value);
482538
483- // Makes sure that previous call results do not replace new ones.
484- if (callId != _onChangedCallId) {
485- return ;
539+ if (! mounted) {
540+ return ;
541+ }
542+
543+ // Makes sure that previous call results do not replace new ones.
544+ if (callId != _onChangedCallId) {
545+ return ;
546+ }
547+ _controller.options = options; // triggers _handleOptionsChanged via listener
548+ } else {
549+ // External controller: caller manages options separately.
550+ // Still update selection validity and visibility for text changes.
551+ _updateSelectionValidity ();
486552 }
487- if (_options.isEmpty != options.isEmpty) {
488- _announceSemantics (options.isNotEmpty);
553+ }
554+
555+ void _handleOptionsChanged () {
556+ final bool optionsWereEmpty = _lastOptionsWereEmpty;
557+ _lastOptionsWereEmpty = _options.isEmpty;
558+ if (optionsWereEmpty != _options.isEmpty) {
559+ _announceSemantics (_options.isNotEmpty);
489560 }
490- _options = options;
491561 _updateHighlight (_highlightedOptionIndex.value);
562+ _updateSelectionValidity ();
563+ }
564+
565+ void _updateSelectionValidity () {
492566 final T ? selection = _selection;
493- if (selection != null && value.text != widget.displayStringForOption (selection)) {
567+ if (selection != null &&
568+ _textEditingController.text != widget.displayStringForOption (selection)) {
494569 _selection = null ;
495570 }
496-
497571 _updateOptionsViewVisibility ();
498572 }
499573
@@ -648,6 +722,10 @@ class _RawAutocompleteState<T extends Object> extends State<RawAutocomplete<T>>
648722 @override
649723 void initState () {
650724 super .initState ();
725+ if (widget.controller != null ) {
726+ widget.controller! .addListener (_handleOptionsChanged);
727+ _lastOptionsWereEmpty = widget.controller! .options.isEmpty;
728+ }
651729 final TextEditingController initialController =
652730 widget.textEditingController ??
653731 (_internalTextEditingController = TextEditingController .fromValue (widget.initialValue));
@@ -659,6 +737,17 @@ class _RawAutocompleteState<T extends Object> extends State<RawAutocomplete<T>>
659737 @override
660738 void didUpdateWidget (RawAutocomplete <T > oldWidget) {
661739 super .didUpdateWidget (oldWidget);
740+ if (! identical (oldWidget.controller, widget.controller)) {
741+ oldWidget.controller? .removeListener (_handleOptionsChanged);
742+ if (oldWidget.controller == null ) {
743+ _internalController? .dispose ();
744+ _internalController = null ;
745+ }
746+ if (widget.controller != null ) {
747+ widget.controller! .addListener (_handleOptionsChanged);
748+ _lastOptionsWereEmpty = widget.controller! .options.isEmpty;
749+ }
750+ }
662751 if (! identical (oldWidget.textEditingController, widget.textEditingController)) {
663752 oldWidget.textEditingController? .removeListener (_onChangedField);
664753 if (oldWidget.textEditingController == null ) {
@@ -679,6 +768,8 @@ class _RawAutocompleteState<T extends Object> extends State<RawAutocomplete<T>>
679768
680769 @override
681770 void dispose () {
771+ widget.controller? .removeListener (_handleOptionsChanged);
772+ _internalController? .dispose ();
682773 widget.textEditingController? .removeListener (_onChangedField);
683774 _internalTextEditingController? .dispose ();
684775 widget.focusNode? .removeListener (_updateOptionsViewVisibility);
0 commit comments