DesignCombobox<T extends Object> class
A text field that suggests options as you type.
Give it options to filter (case-insensitively, by displayStringForOption) or a search that finds them. The look paints the field (fieldBuilder), each option (optionBuilder) and the list's surface (surfaceBuilder); the combobox moves the highlight, scrolls it into view, takes a choice, and announces.
DesignCombobox<String>(options: const ['Apple', 'Pear'], fieldBuilder: (context, field) => EditableText(controller: field.controller, focusNode: field.focusNode, style: const TextStyle(), cursorColor: const Color(0xFF000000), backgroundCursorColor: const Color(0xFF808080), onEditingComplete: field.submit), optionBuilder: (context, option, states) => Text(option))
- Inheritance
-
- Object
- DiagnosticableTree
- Widget
- StatefulWidget
- DesignCombobox
Constructors
-
DesignCombobox({Key? key, required DesignComboboxFieldBuilder fieldBuilder, required DesignOptionBuilder<
T> optionBuilder, Iterable<T> options = const [], DesignOptionSearch<T> ? search, String displayStringForOption(T option) = _string, DesignListSurfaceBuilder? surfaceBuilder, ValueChanged<T> ? onSelected, T? value, bool isOptionEnabled(T option)?, bool highlightFollowsPointer = false, bool requireSelection = false, TextEditingController? controller, FocusNode? focusNode, OptionsViewOpenDirection optionsViewOpenDirection = OptionsViewOpenDirection.mostSpace, double optionsMaxHeight = 300, String? semanticLabel, WidgetBuilder? emptyBuilder, Duration? debounceDuration, WidgetBuilder? loadingBuilder, DesignSearchErrorBuilder? errorBuilder}) -
A combobox over
optionsorsearch.const
Properties
- controller → TextEditingController?
-
The field's text, when the caller holds it. The caller disposes it;
null: the combobox makes its own and disposes it.
final
- debounceDuration → Duration?
-
How long typing rests before search runs: a search per pause, not
per letter. Null (the default) runs it at every change. Filtering
options never waits.
final
- displayStringForOption → String Function(T option)
-
An option's text: what the filter matches and the field shows once it
is taken.
final
- emptyBuilder → WidgetBuilder?
-
Says that nothing matches, in the list's surface, while the field holds
text no option fits. Null: the list just closes.
final
- errorBuilder → DesignSearchErrorBuilder?
-
Says that search failed, in the list's surface, with a way to try
again (DesignSearchError.retry; Down moves the keys there, Enter
runs it); a screen reader hears
DesignLocalizations.searchFailedMessage as it appears, and the focus
stays in the field. Null (the default): the list closes and the error
goes to FlutterError.reportError.
final
- fieldBuilder → DesignComboboxFieldBuilder
-
Paints the field.
final
- focusNode → FocusNode?
-
The field's focus, when the caller holds it. The caller disposes it;
null: the combobox makes its own and disposes it.
final
- hashCode → int
-
The hash code for this object.
no setterinherited
- highlightFollowsPointer → bool
-
Whether the pointer moves the highlight. Off (the default), they are
two places: the pointer's option shows WidgetState.hovered and the
keys' WidgetState.focused, for a look that paints them apart. On, a
pointer moving over an option that can be taken highlights it (no
option shows WidgetState.hovered), the keys go on from there, and the
highlight stays where it is when the pointer leaves the list, as in a
native menu.
final
- isOptionEnabled → bool Function(T option)?
-
Whether an option can be taken; null: all can. A disabled option shows
WidgetState.disabled; the highlight passes over it, and neither a tap
nor Enter takes it.
final
- key → Key?
-
Controls how one widget replaces another widget in the tree.
finalinherited
- loadingBuilder → WidgetBuilder?
-
Says that search is finding options, in the list's surface, while its
future is pending (and while debounceDuration runs); a screen reader
hears DesignLocalizations.loadingLabel as it appears. Null (the
default): the options found last stay until the new ones come.
final
-
onSelected
→ ValueChanged<
T> ? -
Called with the option taken.
final
-
optionBuilder
→ DesignOptionBuilder<
T> -
Paints one option.
final
-
options
→ Iterable<
T> -
The options typing filters, when there is no search.
final
- optionsMaxHeight → double
-
The list's greatest height; past it, it scrolls.
final
- optionsViewOpenDirection → OptionsViewOpenDirection
-
Where the list opens. By default it uses the side of the field with
more available space, accounting for the on-screen keyboard.
final
- requireSelection → bool
-
Whether leaving the field puts back value's text (empty with no
value), so the field never holds text that is not an option: a
searchable select.
final
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
-
search
→ DesignOptionSearch<
T> ? -
Finds the options for a query, in place of filtering options.
final
- semanticLabel → String?
-
What a screen reader calls the list.
final
- surfaceBuilder → DesignListSurfaceBuilder?
-
Paints the list's surface; null shows the bare list.
final
- value → T?
-
The option taken, shown as WidgetState.selected and, when the field
is not being edited, as its text. A list opened while the field shows
it lists every option, its highlight on this one.
final
Methods
-
createElement(
) → StatefulElement -
Creates a StatefulElement to manage this widget's location in the tree.
inherited
-
createState(
) → State< DesignCombobox< T> > -
Creates the mutable state for this widget at a given location in the tree.
override
-
debugDescribeChildren(
) → List< DiagnosticsNode> -
Returns a list of DiagnosticsNode objects describing this node's
children.
inherited
-
debugFillProperties(
DiagnosticPropertiesBuilder properties) → void -
Add additional properties associated with the node.
override
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
toDiagnosticsNode(
{String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode -
Returns a debug representation of the object that is used by debugging
tools and by DiagnosticsNode.toStringDeep.
inherited
-
toString(
{DiagnosticLevel minLevel = DiagnosticLevel.info}) → String -
A string representation of this object.
inherited
-
toStringDeep(
{String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String -
Returns a string representation of this node and its descendants.
inherited
-
toStringShallow(
{String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String -
Returns a one-line detailed description of the object.
inherited
-
toStringShort(
) → String -
A short, textual description of this widget.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited