Display custom options view while options iterable waits to be resolved or is empty #147900

victorsanni · 2024-05-06T23:40:50Z

Currently in Autocomplete, there is no way to:

Display a custom options view when the options returned from optionsBuilder is empty:
Autocomplete widget calls optionsViewBuilder even when optionsBuilder return empty Iterable #108258
This is useful if one wants to display a custom message when the field is focused for the first time, or when no options were found.
Display a loading message while waiting for the optionsBuilder future to be resolved.

This PR fixes these issues by introducing two boolean parameters to Autocomplete and RawAutocomplete: showOptionsViewOnEmptyOptions and showOptionsViewOnPendingOptions.

When set to true, showOptionsViewOnEmptyOptions displays the options view even when the options returned from optionsBuilder is empty.

When set to true, showOptionsViewOnPendingOptions displays the options view just before awaiting the optionsBuilder future, allowing a custom loading view to be shown while waiting for the optionsBuilder future to be resolved.

Fixes #108258 and #147377.

Before:

autocomplete_b4.mov

After:

Autocomplete.video.mov

Pre-launch Checklist

I read the Contributor Guide and followed the process outlined there for submitting PRs.
I read the Tree Hygiene wiki page, which explains my responsibilities.
I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
I signed the CLA.
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is test-exempt.
I followed the breaking change policy and added Data Driven Fixes where supported.
All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

…able

…th-empty-iterable

justinmc

We need make a final decision on if this 2-boolean approach is the best way to go. It looks pretty good in this PR. Maybe the error case that I mentioned in the comments is something we should make sure that it can do. Is there anything else that this 2-boolean approach would not cover? How about that issue that I tagged you in earlier?

examples/api/lib/material/autocomplete/autocomplete.5.dart

justinmc · 2024-05-09T23:21:47Z

examples/api/lib/material/autocomplete/autocomplete.5.dart

+///
+/// This means that the original function will be called only after no calls
+/// have been made for the given Duration.
+_Debounceable<S, T> _debounce<S, T>(_Debounceable<S?, T> function) {


If you totally removed the debouncing from this example, would it be easier to understand the new stuff, or would it be too unrealistic?

Yes, but it might also make it difficult to understand why _isLoading should be set to false only when the current text is equal to the last text searched with (_lastValue). So, if someone were to dup the example, remove the (seemingly) extra variables _lastOptions and _lastValue and later add debouncing, they would probably run into errors and get confused.

packages/flutter/lib/src/material/autocomplete.dart

justinmc · 2024-05-09T23:35:20Z

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

@@ -353,6 +366,9 @@ class _RawAutocompleteState<T extends Object> extends State<RawAutocomplete<T>>
  // Called when _textEditingController changes.
  Future<void> _onChangedField() async {
    final TextEditingValue value = _textEditingController.value;
+    if (widget.showOptionsViewOnUncompletedOptions){
+      _updateOptionsViewVisibility();


How does this affect synchronous values of optionsBuilder? optionsViewBuilder could be called twice back-to-back. Is that something we should avoid or it shouldn't matter?

If optionsBuilder is synchronous, and showOptionsViewOnPendingOptions is set to true, then the options view will just be rebuilt to display its current contents.

I've added a note for users to ignore showOptionsViewOnPendingOptions if their optionsBuilder is synchronous.

packages/flutter/test/widgets/autocomplete_test.dart

justinmc · 2024-05-20T19:04:26Z

Bug report on the example:

Screencast.from.2024-05-20.12-02-59.webm

Using the same steps, one time I also saw the "Loading" disappear and a few seconds later the correct results appeared. Couldn't capture that in the recording though. It probably has to do with subtle timing.

victorsanni · 2024-05-20T22:19:34Z

Bug report on the example:

Screencast.from.2024-05-20.12-02-59.webm
Using the same steps, one time I also saw the "Loading" disappear and a few seconds later the correct results appeared. Couldn't capture that in the recording though. It probably has to do with subtle timing.

Fixing this bug required me to revert the change which terminates _onChangedField if the current textEditingController's text value is equal to the previous value, which means currently _onChangedField completes (rebuilding the options view as a result) on mere selection changes (which is the current behavior that was identified as undesired).

I was also running into another bug where if there was a selection and the app window goes into the background, when the text field is refocused, the loading message displays infinitely. To fix that, I use setState now in the examples to rebuild the widget once loading is completed.

LongCatIsLooong · 2024-05-24T19:56:36Z

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

@@ -157,6 +157,8 @@ class RawAutocomplete<T extends Object> extends StatefulWidget {
    this.onSelected,
    this.textEditingController,
    this.initialValue,
+    this.showOptionsViewOnEmptyOptions = false,
+    this.showOptionsViewOnPendingOptions = false,


It seems to me that these two flags have a lot in common: they both want to show the options view. I think that's a sign that the API could be more generic / flexible. Can we let the user specify what the logic in _canShowOptionsView should look like, and have the current behavior as the default?

I thought the same thing. I'd like to see what that would look like.

LongCatIsLooong · 2024-05-24T19:59:45Z

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

-  bool get _canShowOptionsView => _focusNode.hasFocus && _selection == null && _options.isNotEmpty;
+  bool get _canShowOptionsView => _focusNode.hasFocus && _selection == null &&
+    (_options.isNotEmpty
+    || widget.showOptionsViewOnEmptyOptions


nit: { } for multiline expressions per the style guide, instead of =>.

Also the logic doesn't seem correct? showOptionsViewOnEmptyOptions and showOptionsViewOnPendingOptions seem to have the same effect here, but they are different flags?

victorsanni added 16 commits April 22, 2024 14:59

Invoke optionsViewBuilder even when optionsBuilder returns empty Iter…

fd17003

…able

Merge branch 'flutter:master' into allow-autocomplete-options-show-wi…

d8d912f

…th-empty-iterable

Autocomplete fixes with callback

8d6f10e

Documentation fixes

096a31c

No more breaking change

baac732

Merge branch 'flutter:master' into autocomplete-with-callback

262e974

Merge branch 'flutter:master' into autocomplete-with-callback

deea5e0

Changed callback name and update documentation

57f1c1c

Made work with bools

3c1dca4

Added test for autocomplete

5510b76

revert

99adc7c

Add test

bd72d50

Autocomplete with two bools and tests

f4aca1a

Merge branch 'flutter:master' into autocomplete-with-bools

dc82b9f

Added examples and accompanying tests

93b9884

Update documentation to include dartpad tool

aeadb81

github-actions bot added framework flutter/packages/flutter repository. See also f: labels. f: material design flutter/packages/flutter/material repository. d: api docs Issues with https://api.flutter.dev/ d: examples Sample code and demos labels May 6, 2024

victorsanni requested a review from justinmc May 6, 2024 23:42

Add license header to autocomplete.5.dart

1ffea27

victorsanni changed the title ~~Enable displaying custom options view while options wait to be resolved or is empty~~ Display custom options view while options iterable waits to be resolved or is empty May 7, 2024

victorsanni marked this pull request as ready for review May 7, 2024 20:57

Merge branch 'master' into autocomplete-with-bools

0f2fed5

justinmc reviewed May 9, 2024

View reviewed changes

victorsanni added 4 commits May 10, 2024 11:17

Applied most of Justin's suggested changes

1be2601

Fixed small bugs

adbeaf5

Added error handling with tests

7b69311

Add missing type annotation

4558f74

victorsanni added 5 commits May 13, 2024 14:48

Merge branch 'master' into autocomplete-with-bools

f1e3235

Merge branch 'master' into autocomplete-with-bools

4e00279

Merge branch 'master' into autocomplete-with-bools

c34cf65

Merge branch 'master' into autocomplete-with-bools

03656c6

Merge branch 'master' into autocomplete-with-bools

f3e4405

Fix bug to show correct options view

ebd28ac

Make autocomplete work with debouncing

d9b9c4f

victorsanni mentioned this pull request May 23, 2024

Stop autocomplete options builder from calling on text selection changes #148995

Open

9 tasks

Remove unnecessary setState

fa214a1

victorsanni requested review from Renzo-Olivares and LongCatIsLooong May 24, 2024 17:50

LongCatIsLooong reviewed May 24, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Display custom options view while options iterable waits to be resolved or is empty #147900

Display custom options view while options iterable waits to be resolved or is empty #147900

victorsanni commented May 6, 2024 •

edited

justinmc left a comment

justinmc May 9, 2024

victorsanni May 10, 2024

justinmc May 9, 2024

victorsanni May 10, 2024

justinmc commented May 20, 2024

victorsanni commented May 20, 2024

LongCatIsLooong May 24, 2024 •

edited

justinmc May 24, 2024

LongCatIsLooong May 24, 2024

LongCatIsLooong May 24, 2024

Display custom options view while options iterable waits to be resolved or is empty #147900

Are you sure you want to change the base?

Display custom options view while options iterable waits to be resolved or is empty #147900

Conversation

victorsanni commented May 6, 2024 • edited

Pre-launch Checklist

justinmc left a comment

Choose a reason for hiding this comment

justinmc May 9, 2024

Choose a reason for hiding this comment

victorsanni May 10, 2024

Choose a reason for hiding this comment

justinmc May 9, 2024

Choose a reason for hiding this comment

victorsanni May 10, 2024

Choose a reason for hiding this comment

justinmc commented May 20, 2024

victorsanni commented May 20, 2024

LongCatIsLooong May 24, 2024 • edited

Choose a reason for hiding this comment

justinmc May 24, 2024

Choose a reason for hiding this comment

LongCatIsLooong May 24, 2024

Choose a reason for hiding this comment

LongCatIsLooong May 24, 2024

Choose a reason for hiding this comment

victorsanni commented May 6, 2024 •

edited

LongCatIsLooong May 24, 2024 •

edited