@@ -121,19 +121,46 @@ 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+ _options = value;
146+ notifyListeners ();
147+ }
148+ }
149+
124150// TODO(justinmc): Mention AutocompleteCupertino when it is implemented.
125151/// {@template flutter.widgets.RawAutocomplete.RawAutocomplete}
126152/// A widget for helping the user make a selection by entering some text and
127153/// choosing from among a list of options.
128154///
129155/// The user's text input is received in a field built with the
130156/// [fieldViewBuilder] parameter. The options to be displayed are determined
131- /// using [optionsBuilder] and rendered with [optionsViewBuilder] .
157+ /// using [optionsBuilder] (or, for [RawAutocomplete] , a
158+ /// [RawAutocompleteController] ) and
159+ /// rendered with [optionsViewBuilder] .
132160///
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.
161+ /// The options view opens when the field gains focus and there is at least one
162+ /// option available. It closes when the user selects an option, when there are
163+ /// no matching options, or when the field loses focus.
137164/// {@endtemplate}
138165///
139166/// This is a core framework widget with very basic UI.
@@ -171,12 +198,16 @@ enum OptionsViewOpenDirection {
171198class RawAutocomplete <T extends Object > extends StatefulWidget {
172199 /// Create an instance of RawAutocomplete.
173200 ///
174- /// [displayStringForOption] , [optionsBuilder] and [optionsViewBuilder] must
175- /// not be null.
201+ /// Exactly one of [optionsBuilder] or [controller] must be provided.
202+ /// When [optionsBuilder] is provided, the widget internally calls it when the
203+ /// text field's [TextEditingValue] changes and manages the result.
204+ /// When [controller] is provided, the caller sets
205+ /// [RawAutocompleteController.options] directly and the widget reacts.
176206 const RawAutocomplete ({
177207 super .key,
178208 required this .optionsViewBuilder,
179- required this .optionsBuilder,
209+ this .optionsBuilder,
210+ this .controller,
180211 this .optionsViewOpenDirection = OptionsViewOpenDirection .down,
181212 this .displayStringForOption = defaultStringForOption,
182213 this .fieldViewBuilder,
@@ -193,6 +224,10 @@ class RawAutocomplete<T extends Object> extends StatefulWidget {
193224 assert (
194225 ! (textEditingController != null && initialValue != null ),
195226 'textEditingController and initialValue cannot be simultaneously defined.' ,
227+ ),
228+ assert (
229+ (optionsBuilder == null ) != (controller == null ),
230+ 'Exactly one of optionsBuilder or controller must be provided.' ,
196231 );
197232
198233 /// {@template flutter.widgets.RawAutocomplete.fieldViewBuilder}
@@ -277,7 +312,19 @@ class RawAutocomplete<T extends Object> extends StatefulWidget {
277312 /// A function that returns the current selectable options objects given the
278313 /// current TextEditingValue.
279314 /// {@endtemplate}
280- final AutocompleteOptionsBuilder <T > optionsBuilder;
315+ ///
316+ /// Mutually exclusive with [controller] . Exactly one must be provided.
317+ final AutocompleteOptionsBuilder <T >? optionsBuilder;
318+
319+ /// A controller that allows the caller to manage the options list directly.
320+ ///
321+ /// When provided, the caller sets [RawAutocompleteController.options]
322+ /// directly and the widget reacts to changes. This is useful when the
323+ /// options depend on criteria beyond just the [TextEditingValue] , which is
324+ /// the only input that [optionsBuilder] receives.
325+ ///
326+ /// Mutually exclusive with [optionsBuilder] . Exactly one must be provided.
327+ final RawAutocompleteController <T >? controller;
281328
282329 /// The [TextEditingController] that is used for the text field.
283330 ///
@@ -383,7 +430,14 @@ class _RawAutocompleteState<T extends Object> extends State<RawAutocomplete<T>>
383430 DismissIntent : CallbackAction <DismissIntent >(onInvoke: _hideOptions),
384431 };
385432
386- Iterable <T > _options = Iterable <T >.empty ();
433+ RawAutocompleteController <T >? _internalController;
434+ RawAutocompleteController <T > get _controller {
435+ return widget.controller ??
436+ (_internalController ?? = RawAutocompleteController <T >()
437+ ..addListener (_handleOptionsChanged));
438+ }
439+ Iterable <T > get _options => _controller.options;
440+ bool _lastOptionsWereEmpty = true ;
387441 T ? _selection;
388442 // Set the initial value to null so when this widget gets focused for the first
389443 // time it will try to run the options view builder.
@@ -472,28 +526,43 @@ class _RawAutocompleteState<T extends Object> extends State<RawAutocomplete<T>>
472526 _userHidOptions = false ;
473527 }
474528 _lastFieldText = value.text;
475- _onChangedCallId += 1 ;
476- final int callId = _onChangedCallId;
477- final Iterable <T > options = await widget.optionsBuilder (value);
478529
479- if (! mounted) {
480- return ;
481- }
530+ if (widget.optionsBuilder case final optionsBuilder? ) {
531+ _onChangedCallId += 1 ;
532+ final int callId = _onChangedCallId;
533+ final Iterable <T > options = await optionsBuilder (value);
482534
483- // Makes sure that previous call results do not replace new ones.
484- if (callId != _onChangedCallId) {
485- return ;
535+ if (! mounted) {
536+ return ;
537+ }
538+
539+ // Makes sure that previous call results do not replace new ones.
540+ if (callId != _onChangedCallId) {
541+ return ;
542+ }
543+ _controller.options = options; // triggers _handleOptionsChanged via listener
544+ } else {
545+ // External controller: caller manages options separately.
546+ // Still update selection validity and visibility for text changes.
547+ _updateSelectionValidity ();
486548 }
487- if (_options.isEmpty != options.isEmpty) {
488- _announceSemantics (options.isNotEmpty);
549+ }
550+
551+ void _handleOptionsChanged () {
552+ final bool optionsWereEmpty = _lastOptionsWereEmpty;
553+ _lastOptionsWereEmpty = _options.isEmpty;
554+ if (optionsWereEmpty != _options.isEmpty) {
555+ _announceSemantics (_options.isNotEmpty);
489556 }
490- _options = options;
491557 _updateHighlight (_highlightedOptionIndex.value);
558+ _updateSelectionValidity ();
559+ }
560+
561+ void _updateSelectionValidity () {
492562 final T ? selection = _selection;
493- if (selection != null && value .text != widget.displayStringForOption (selection)) {
563+ if (selection != null && _textEditingController .text != widget.displayStringForOption (selection)) {
494564 _selection = null ;
495565 }
496-
497566 _updateOptionsViewVisibility ();
498567 }
499568
@@ -648,6 +717,10 @@ class _RawAutocompleteState<T extends Object> extends State<RawAutocomplete<T>>
648717 @override
649718 void initState () {
650719 super .initState ();
720+ if (widget.controller != null ) {
721+ widget.controller! .addListener (_handleOptionsChanged);
722+ _lastOptionsWereEmpty = widget.controller! .options.isEmpty;
723+ }
651724 final TextEditingController initialController =
652725 widget.textEditingController ??
653726 (_internalTextEditingController = TextEditingController .fromValue (widget.initialValue));
@@ -659,6 +732,17 @@ class _RawAutocompleteState<T extends Object> extends State<RawAutocomplete<T>>
659732 @override
660733 void didUpdateWidget (RawAutocomplete <T > oldWidget) {
661734 super .didUpdateWidget (oldWidget);
735+ if (! identical (oldWidget.controller, widget.controller)) {
736+ oldWidget.controller? .removeListener (_handleOptionsChanged);
737+ if (oldWidget.controller == null ) {
738+ _internalController? .dispose ();
739+ _internalController = null ;
740+ }
741+ if (widget.controller != null ) {
742+ widget.controller! .addListener (_handleOptionsChanged);
743+ _lastOptionsWereEmpty = widget.controller! .options.isEmpty;
744+ }
745+ }
662746 if (! identical (oldWidget.textEditingController, widget.textEditingController)) {
663747 oldWidget.textEditingController? .removeListener (_onChangedField);
664748 if (oldWidget.textEditingController == null ) {
@@ -679,6 +763,8 @@ class _RawAutocompleteState<T extends Object> extends State<RawAutocomplete<T>>
679763
680764 @override
681765 void dispose () {
766+ widget.controller? .removeListener (_handleOptionsChanged);
767+ _internalController? .dispose ();
682768 widget.textEditingController? .removeListener (_onChangedField);
683769 _internalTextEditingController? .dispose ();
684770 widget.focusNode? .removeListener (_updateOptionsViewVisibility);
0 commit comments