Unverified Commit f131c80b authored by Hans Muller's avatar Hans Muller Committed by GitHub

Updated DropdownButton docs (#27042)

parent 91fd89e8
......@@ -476,11 +476,55 @@ class DropdownButtonHideUnderline extends InheritedWidget {
/// shows the currently selected item as well as an arrow that opens a menu for
/// selecting another item.
///
/// The type `T` is the type of the values the dropdown menu represents. All the
/// entries in a given menu must represent values with consistent types.
/// The type `T` is the type of the [value] that each dropdown item represents.
/// All the entries in a given menu must represent values with consistent types.
/// Typically, an enum is used. Each [DropdownMenuItem] in [items] must be
/// specialized with that same type argument.
///
/// The [onChanged] callback should update a state variable that defines the
/// dropdown's value. It should also call [State.setState] to rebuild the
/// dropdown with the new value.
///
/// {@tool snippet --template=stateful_widget}
///
/// This sample shows a `DropdownButton` whose value is one of
/// "One", "Two", "Free", or "Four".
///
/// ```dart preamble
/// String dropdownValue = 'One';
/// ```
///
/// ```dart
/// Widget build(BuildContext context) {
/// return Scaffold(
/// body: Center(
/// child: DropdownButton<String>(
/// value: dropdownValue,
/// onChanged: (String newValue) {
/// setState(() {
/// dropdownValue = newValue;
/// });
/// },
/// items: <String>['One', 'Two', 'Free', 'Four']
/// .map<DropdownMenuItem<String>>((String value) {
/// return DropdownMenuItem<String>(
/// value: value,
/// child: Text(value),
/// );
/// })
/// .toList(),
/// ),
/// ),
/// );
/// }
/// ```
/// {@end-tool}
///
/// If the [onChanged] callback is null or the list of [items] is null
/// then the dropdown button will be disabled, i.e. its arrow will be
/// displayed in grey and it will not respond to input. A disabled button
/// will display the [disabledHint] widget if it is non-null.
///
/// Requires one of its ancestors to be a [Material] widget.
///
/// See also:
......@@ -493,12 +537,14 @@ class DropdownButtonHideUnderline extends InheritedWidget {
class DropdownButton<T> extends StatefulWidget {
/// Creates a dropdown button.
///
/// The [items] must have distinct values and if [value] isn't null it must be among them.
/// If [items] or [onChanged] is null, the button will be disabled, the down arrow will be grayed out, and
/// the [disabledHint] will be shown (if provided).
/// The [items] must have distinct values. If [value] isn't null then it
/// must be equal to one of the [DropDownMenuItem] values. If [items] or
/// [onChanged] is null, the button will be disabled, the down arrow
/// will be greyed out, and the [disabledHint] will be shown (if provided).
///
/// The [elevation] and [iconSize] arguments must not be null (they both have
/// defaults, so do not need to be specified).
/// defaults, so do not need to be specified). The boolean [isDense] and
/// [isExpanded] arguments must not be null.
DropdownButton({
Key key,
@required this.items,
......@@ -512,14 +558,23 @@ class DropdownButton<T> extends StatefulWidget {
this.isDense = false,
this.isExpanded = false,
}) : assert(items == null || value == null || items.where((DropdownMenuItem<T> item) => item.value == value).length == 1),
super(key: key);
assert(elevation != null),
assert(iconSize != null),
assert(isDense != null),
assert(isExpanded != null),
super(key: key);
/// The list of possible items to select among.
/// The list of items the user can select.
///
/// If the [onChanged] callback is null or the list of items is null
/// then the dropdown button will be disabled, i.e. its arrow will be
/// displayed in grey and it will not respond to input. A disabled button
/// will display the [disabledHint] widget if it is non-null.
final List<DropdownMenuItem<T>> items;
/// The currently selected item, or null if no item has been selected. If
/// value is null then the menu is popped up as if the first item was
/// selected.
/// The value of the currently selected [DropdownMenuItem], or null if no
/// item has been selected. If `value` is null then the menu is popped up as
/// if the first item were selected.
final T value;
/// Displayed if [value] is null.
......@@ -531,11 +586,17 @@ class DropdownButton<T> extends StatefulWidget {
final Widget disabledHint;
/// Called when the user selects an item.
///
/// If the [onChanged] callback is null or the list of [items] is null
/// then the dropdown button will be disabled, i.e. its arrow will be
/// displayed in grey and it will not respond to input. A disabled button
/// will display the [disabledHint] widget if it is non-null.
final ValueChanged<T> onChanged;
/// The z-coordinate at which to place the menu when open.
///
/// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12, 16, 24
/// The following elevations have defined shadows: 1, 2, 3, 4, 6, 8, 9, 12,
/// 16, and 24. See [kElevationToShadow].
///
/// Defaults to 8, the appropriate elevation for dropdown buttons.
final int elevation;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment