Add DropdownMenu.decorationBuilder

[bleroux]

Description

This PR adds DropdownMenu.decorationBuilder.
The goal is to make DropdownMenu more flexible.

Before this PR, several fields are used by DropdownMenu to create an inner InputDecoration. This approach has several limitations:

• InputDecoration has more fields that the ones that are exposed
• DropdownMenu makes some choices that can't be change. Especially, it creates an IconButton (with hardcoded padding) which is passed to InputDecoration.suffixIcon. This inner IconButton introduces some difficulty related to focus management and UI customization.

The new DropdownMenu.decorationBuilder property offers users a way to take control on the inner InputDecoration in a non-breaking way.

In a future PR, this property will help replacing the default IconButton.
Currently users can replace the IconButton using this code sample:

DropdownMenu without IconButton

import'package:flutter/material.dart';
voidmain() {
runApp(MyApp());
}
classMyAppextendsStatelessWidget {
MyApp({super.key});
finalList<DropdownMenuEntry<String>> menuEntries = [
"Red",
"Green",
"Blue",
].map((t) =>DropdownMenuEntry<String>(label: t, value: t)).toList();
@overrideWidgetbuild(BuildContext context) {
returnMaterialApp(
home:Scaffold(
body:Center(
child:SizedBox(
width:220,
child:DropdownMenu<String>(
expandedInsets:EdgeInsets.zero,
requestFocusOnTap:true,
dropdownMenuEntries: menuEntries,
decorationBuilder: (context, controller) {
returnInputDecoration(
labelText:'Label text',
helperText:'Select a color or enter one',
suffixIcon: controller.isOpen
?constIcon(Icons.arrow_drop_up)
:constIcon(Icons.arrow_drop_down),
);
},
),
),
),
),
);
}
}

Related Issue

FixesDropDownMenu secondary trailing widget
Will help for Make DropdownMenu's trailing icon not focusable by default

Related discussions

#175847 (comment)
#175558 (comment)

Tests

• Adds 7 tests.

[gemini-code-assist]

Code Review

This pull request introduces DropdownMenu.decorationBuilder, a new property that provides a more flexible way to customize the InputDecoration of the DropdownMenu. This is a significant improvement over the previous method of exposing individual decoration properties. The implementation is robust, with assertions to prevent misuse and a clean refactoring that maintains backward compatibility. The accompanying tests are thorough. My review includes a couple of minor suggestions to fix typos in the documentation and a small correction in one of the new tests.

[QuncCccccc]

I like this approach! Thank you for the improvement. Overall this looks good to me:) Will take another look tomorrow.

[QuncCccccc]

Do you think if there will be a case where the user doesn't want the sufficIcon at all? I'm thinking whether we should still give it a default value when suffixIcon is null.

[bleroux]

Interesting.
The property DropdownMenu.showTrailingIcon was added some time ago in #167782 for that purpose.

Because DropdownMenu.decorationBuilder is new we can decide to use a different solution. Nonetheless, If we don't add a default suffix when suffixIcon is null, most of the users will have to provide their implementation or we have to offer them an API to get the default Icon. It seems to add complexity for a use case which is somewhat specific.

[Gustl22]

I'd propose to always add the default icon, also with a custom decoration (when the user adds an additinal trailing icon, then keep it in a Row). And the user can still disable it via the property showTrailingIcon. That way the dev does not need to implement it, e.g. also with providing more additional trailing actions, but still has the opportunity to remove it.
That way it has a purpose in all cases, while providing maximum flexibility and minimal effort for the dev.

The other way around: in the current implementation, if the user defines its own trailing icon, the showTrailingIcon does not have any effect, right?

[bleroux]

I'd propose to always add the default icon, also with a custom decoration (when the user adds an additinal trailing icon, then keep it in a Row)

Adding a Row fits specific use cases and for these use cases it might be better for us to expose the default button construction if you think this would be interesting and let users add a Row (or something else) if needed (that way they can control padding for instance or anything matching their design).
My reasonning is to remove as much as possible custom rendering logic outside of DropdownMenu. In that particular case, InputDecorator already implements APIs that comply with M3 spec (padding, defaults colors, borders, etc) and offer flexibility (InputDecoration.suffix, InputDecoration.suffixIcon, etc).

The other way around: in the current implementation, if the user defines its own trailing icon, the showTrailingIcon does not have any effect, right?

Yes. It surely should be documented (in fact the best move would probably to rename showTrailingIcon to showDefaultTrailingIcon in that case). We can also decide to ignore InputDecoration.suffixIcon if showTrailingIcon is false, it might be easier to document/understand.

[Gustl22]

Adding a Row fits specific use cases and for these use cases it might be better for us to expose the default button construction if you think this would be interesting and let users add a Row

Good point.
Of course the Row was just meant as an internal helper to still be able to access the default trailing icon. But yes, it would then only serve in that (in my opinion most common) use case, and shrinks flexibility how (e.g. in which order) to use it.

I personally don't need the default trailing button, as the fuctionality can easily be recreated with the controller. Not sure if folks would notice / search for the constructor of the default icon.

Yes. It surely should be documented (in fact the best move would probably to rename showTrailingIcon to showDefaultTrailingIcon in that case). We can also decide to ignore InputDecoration.suffixIcon if showTrailingIcon is false, it might be easier to document/understand.

Sounds reasonable. Happy with both variants :)

Btw thank you for your efforts!

[QuncCccccc]

when suffixIcon is null, most of the users will have to provide their implementation or we have to offer them an API to get the default Icon. It seems to add complexity for a use case which is somewhat specific.

I see, it makes sense to me.

[QuncCccccc]

LGTM. Thank you for adding all the tests:)

[Gustl22]

@bleroux I noticed a little naming improvement: Maybe it makes sense to call the parameter menuController, as in the widget itself controller is always referenced as the TextEditingController. Maybe it makes sense to rename the default param name to reduce confusion (?)

[bleroux]

@Gustl22 I usually try to use more precise names. In the context of DropdownMenu, there are multiple controllers so it could help, especially for instance variables.

About this particular case, because the name is just in a typedef and the explicit type is just before, I probably preferred controller as the type of controller was explicit.
Is this variable visible anywhere else? Maybe when using completion?

[Gustl22]

Yes this is only a problem of code completion for now.

I just stumbled across this scenario, where I wanted to add a clear button:

classSimpleDropdown<TextendsObject> extendsStatefulWidget {
finalIterable<DropdownMenuEntry<T>> options;
finalT? selected;
finalvoidFunction(T? value)? onChange;
finalFormFieldSetter<T>? onSaved;
constSimpleDropdown({requiredthis.options, requiredthis.selected, this.onChange, this.onSaved});
@overrideState<SimpleDropdown<T>> createState() =>_SimpleDropdownState<T>();
}
class_SimpleDropdownState<TextendsObject> extendsState<SimpleDropdown<T>> {
final _textEditingController =TextEditingController();
@overrideWidgetbuild(BuildContext context) {
final items = widget.options.toList();
returnDropdownMenuFormField<T>(
initialSelection: widget.selected,
controller: _textEditingController,
onSelected: widget.onChange,
onSaved: widget.onSaved,
dropdownMenuEntries: items,
decorationBuilder:
(context, menuController) =>InputDecoration(
suffixIcon:IconButton(onPressed: () => _textEditingController.clear(), icon:Icon(Icons.clear)),
),
);
}
}

I needed to use a StatefulWidget, because the TextEditingController was not provided by the decorationBuilder.
For me it would make sense to have both controllers available in the callback, or none (so I should pass both the MenuController and the TextEditingController to the DropdownMenu).
Its not per se bad, how it is right now. Just wanted to hear your opinion, what makes MenuController more valuable to exist in the callback than the TextEditingController, which might be the option to mimic the current behavior of opening and closing.

[bleroux]

Just wanted to hear your opinion, what makes MenuController more valuable to exist in the callback than the TextEditingController, which might be the option to mimic the current behavior of opening and closing.

Yes, the reasoning was to give an easy way to reproduce the default behavior,
Another reason might be that I started to work on this before the DropdownMenu.menuController property was added (some weeks before my PR, see #175039).